Standalone

Run Agentgateway as a standalone binary on any Linux, macOS, or Windows host.

Running Agentgateway as a standalone binary is the simplest deployment model. The proxy listens for MCP and A2A traffic, serves the admin UI, and exposes metrics and readiness endpoints — all from a single process.

Prerequisites

To build from source you need:

• Rust 1.86+ — install via rustup
• npm 10+ — required to build the admin UI

Build from source

1. Build the admin UI

   The UI is a separate npm project that gets embedded into the binary at compile time.

   cd ui
   npm install
   npm run build
   
2. Build the binary

   Return to the repository root and build a release binary with the ui feature enabled.

   export CARGO_NET_GIT_FETCH_WITH_CLI=true
   make build
   

   This runs cargo build --release --features ui and places the binary at ./target/release/agentgateway.

3. Verify the build

   ./target/release/agentgateway --version
   

Running Agentgateway

Release binary

Pass a configuration file with the -f flag:

./target/release/agentgateway -f config.yaml

cargo run

During development you can skip the explicit build step:

cargo run -- -f config.yaml

cargo run compiles a debug build by default. For performance testing or production use, always use the release binary.

Once started, open your browser and navigate to http://localhost:15000/ui to access the admin UI.

Configuration file

Agentgateway accepts a JSON or YAML configuration file. The example below is from manifests/localhost-config.json in the repository — it starts an SSE listener on port 8080 with JWT authentication and connects to a local XDS control plane:

localhost-config.json

{
  "type": "xds",
  "xds_address": "http://127.0.0.1:9977",
  "metadata": {},
  "alt_xds_hostname": "agentgateway.default.svc.cluster.local",
  "listener": {
    "type": "sse",
    "host": "0.0.0.0",
    "port": 8080,
    "authn": {
      "type": "jwt",
      "issuer": ["me"],
      "audience": ["me.com"],
      "jwks": {
        "type": "local",
        "source": {
          "type": "file",
          "data": "manifests/jwt/pub-key"
        }
      }
    }
  }
}

Static configuration options

The following fields under the config key control the server’s built-in listeners. All values are strings in ip:port format.

Field	Description	Default
config.adminAddr	Admin UI address	0.0.0.0:15000
config.statsAddr	Prometheus metrics address	0.0.0.0:15020
config.readinessAddr	Readiness probe address	0.0.0.0:15021
config.workerThreads	Number of Tokio worker threads	CPU count

Example static config block

config.yaml

config:
  adminAddr: "0.0.0.0:15000"
  statsAddr: "0.0.0.0:15020"
  readinessAddr: "0.0.0.0:15021"
  workerThreads: 4

Environment variables

Several settings can be overridden with environment variables without changing the config file:

Variable	Description
CARGO_NET_GIT_FETCH_WITH_CLI	Use git CLI for Cargo dependency fetches (required in some corporate networks)
DNS_EDNS0	Enable or disable EDNS0 in the DNS resolver (true / false)
VERSION	Version string embedded in the binary at build time
GIT_REVISION	Git revision string embedded in the binary at build time

Session encryption

To enable encrypted session tokens, generate a 32-byte key and add it to your configuration:

openssl rand -hex 32

config.yaml

config:
  session:
    key: "<output from openssl rand -hex 32>"

If config.session.key is not set, session tokens will not be encrypted. Always set this value in production deployments.

Signal handling and graceful shutdown

Agentgateway responds to standard POSIX signals:

• SIGTERM — begins a graceful shutdown, waiting for in-flight requests to complete before exiting
• SIGINT (Ctrl+C) — same as SIGTERM; safe for interactive use

Two configuration fields control how long the process waits during shutdown:

config.yaml

config:
  connectionTerminationDeadline: "30s"
  connectionMinTerminationDeadline: "5s"

Configuration file watching

When running in static (non-XDS) mode, Agentgateway watches the config file for changes and reloads dynamically without restarting the process. This means you can update routing rules, policies, or backend addresses and have them take effect within seconds.

For XDS-based deployments the control plane pushes updates over gRPC, so file watching is not used. See the Kubernetes deployment guide for details.

Production considerations

Use the release build

Always run make build (which sets --release) in production. Debug builds are significantly slower and produce much larger binaries.

Set worker threads

Set config.workerThreads to match the number of CPU cores available to the process, especially when running inside a container with a CPU limit.

Secure the admin UI

Bind config.adminAddr to a loopback address (127.0.0.1:15000) or an internal network interface in production environments. The admin UI has no built-in authentication.

Enable session encryption

Generate a config.session.key with openssl rand -hex 32 and store it in a secrets manager. Rotate the key during scheduled maintenance windows.