# How Trivy Client-Server Mode Works and When to Use It

> Discover Trivy client-server mode. Learn how the persistent server and lightweight clients optimize scans by running the database centrally and caching metadata. Understand when to leverage this mode for efficient vulnerability...

- Repository: [Aqua Security/trivy](https://github.com/aquasecurity/trivy)
- Tags: internals
- Published: 2026-03-23

---

**Trivy client-server mode runs a persistent server that hosts the vulnerability database and optionally caches artifact metadata, while lightweight clients send scan targets via HTTP/Twirp RPC and receive results without downloading the ~2 GB database themselves.**

Trivy client-server mode centralizes heavy resource management in a long-running server process while distributing lightweight scanning operations across multiple machines. In the `aquasecurity/trivy` repository, this architecture separates the vulnerability database (approximately 2 GB) and artifact caching from the scanning logic, allowing CI agents and edge devices to operate with minimal overhead. Understanding how this mode functions helps you optimize scan performance in distributed environments.

## Architecture Overview

### The Server Component

The Trivy server starts an HTTP listener (default `localhost:8080`) and registers two Twirp RPC services in [`pkg/rpc/server/server.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/rpc/server/server.go). The `Scanner` service performs actual vulnerability, license, and misconfiguration scans, while the `Cache` service stores artifact metadata to prevent redundant layer downloads. Database initialization occurs via `vulnerability.NewClient` inside `initializeScanServer`, ensuring the vulnerability database is ready before accepting requests.

### The Client Component

The client operates as a thin CLI wrapper defined in [`pkg/rpc/client/client.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/rpc/client/client.go) that constructs protobuf requests and transmits them to the server's `/twirp` endpoint. When you invoke `trivy image --server http://host:port`, the client builds an `rpcScanner.ScanRequest` and sends it to `<server>/twirp/github.com/aquasecurity.trivy/rpc.scanner.Scanner/Scan`. The client then converts the `rpcScanner.ScanResponse` back into Trivy's native `types.Report` for display.

## Request Lifecycle in Client-Server Mode

Understanding the request flow clarifies how Trivy client-server mode minimizes client-side resource consumption.

1. **Server Initialization**: The `server.Run` function in [`pkg/rpc/server/listen.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/rpc/server/listen.go) creates an `http.Server` with a `ServeMux` that registers the Twirp handlers. It parses flags for listen address, authentication tokens, and cache configuration from [`pkg/commands/app.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/app.go).

2. **Client Invocation**: The CLI parses the `--server` flag in [`pkg/commands/app.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/app.go) and invokes `client.Service.Scan`, which marshals the target (image name, file path, or repository URL) into a protobuf message.

3. **Remote Execution**: The server's `ScanServer.Scan` method receives the request, invokes the underlying local scan service, and returns a protobuf-encoded response containing vulnerability findings.

4. **Result Rendering**: The client deserializes the response and renders it according to the selected output format (table, JSON, SARIF, etc.).

## When to Use Trivy Client-Server Mode

**Multiple CI Agents**: When numerous build nodes need to scan containers but you want to avoid each node downloading the ~2 GB vulnerability database. The single server holds the DB, reducing network I/O and startup time across your fleet.

**Centralized Policy Enforcement**: Use this mode to enforce shared ignore rules, custom database mirrors, or uniform vulnerability definitions. The server configuration propagates to all clients automatically.

**High-Throughput Scanning**: For large CI pipelines or CI/CD SaaS environments, the `Cache` service prevents repeated layer pulls for identical images, significantly accelerating subsequent scans of the same base images.

**Security-Sensitive Environments**: In scenarios where you cannot expose raw files to remote services, note that vulnerability scanning runs on the server while **misconfiguration** and **secret** detection execute locally on the client, keeping sensitive file contents decentralized.

**Resource-Constrained Nodes**: Edge devices and low-memory containers benefit from negligible client resource usage, while the server runs on more powerful infrastructure.

## Configuration Examples

Start a server with authentication:

```bash

# Start server on all interfaces with token protection

trivy server --listen 0.0.0.0:8080 --token my-secret-token

```

Scan via client:

```bash

# Scan a container image

trivy image --server http://localhost:8080 --token my-secret-token alpine:3.10

# Scan filesystem

trivy fs --server http://localhost:8080 --severity HIGH ./my-app/

# Scan a remote repository

trivy repo https://github.com/example/project --server http://localhost:8080

```

Health checks:

```bash

# Check server health (no auth required)

curl -s http://localhost:8080/healthz

# Get version and DB metadata

curl -s http://localhost:8080/version | jq

```

## Key Implementation Files

Understanding these source files clarifies how data flows through the system:

- [`pkg/commands/app.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/commands/app.go): Defines the `server` sub-command, flag parsing for `--listen` and `--token`, and client-side `--server` flag handling.
- [`pkg/rpc/server/server.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/rpc/server/server.go): Implements the `Scanner` and `Cache` Twirp services, including `ScanServer.Scan` and cache management logic.
- [`pkg/rpc/server/listen.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/rpc/server/listen.go): Constructs the HTTP server, registers Twirp handlers on the `ServeMux`, and manages the server lifecycle.
- [`pkg/rpc/client/client.go`](https://github.com/aquasecurity/trivy/blob/main/pkg/rpc/client/client.go): Handles client-side RPC calls, version negotiation, and response deserialization.

## Summary

- Trivy client-server mode separates the heavy vulnerability database (~2 GB) from lightweight scanning clients using HTTP/Twirp RPC.
- The server exposes two services: `Scanner` for vulnerability analysis and `Cache` for artifact metadata storage.
- Clients send minimal target information and receive full reports without downloading or storing vulnerability data locally.
- Ideal for CI/CD fleets, resource-constrained environments, and centralized policy management scenarios.

## Frequently Asked Questions

### Does the Trivy client download the vulnerability database in client-server mode?

No. In client-server mode, only the server downloads and maintains the vulnerability database. Clients transmit target specifications (image names, file paths) to the server and receive processed results, eliminating the ~2 GB download requirement per client.

### How does the client authenticate with the Trivy server?

Authentication uses the `--token` flag on both sides. Start the server with `--token my-secret-token`, then configure clients with `--token my-secret-token` and `--server http://host:port`. The token is transmitted via HTTP headers in the Twirp requests.

### What happens if the Trivy server is unavailable during a scan?

The client requires an active connection to the server to perform vulnerability scans. If the server is unreachable, the client returns a connection error and exits. For local-only operation, you must run Trivy in standalone mode without the `--server` flag.

### Can I run secret detection and misconfiguration scans in client-server mode?

Secret detection and misconfiguration scanning execute locally on the client rather than on the server. According to the `aquasecurity/trivy` documentation, only vulnerability database lookups are centralized; sensitive file contents for secret scanning remain on the client machine for security reasons.