Configuration reference overview

Agentgateway uses a layered configuration system. Global settings like logging and ports are fixed at startup via static configuration. Routing, backends, and policies are managed at runtime via local or XDS configuration. This separation keeps the hot path free from global restarts while still enabling zero-downtime routing changes.

The three layers

Static configuration

Static configuration is read exactly once during process startup. It controls global settings such as:

Admin, stats, and readiness server addresses
Worker thread count
Logging format and level
Tracing and metrics settings
DNS resolver behavior
Session key for encrypted session tokens
Connection to an XDS control plane

Static config is provided through a YAML or JSON file passed via the -f flag, or through environment variables. It cannot be changed without restarting the process.See all static config fields →

Local configuration

Local configuration is loaded from the same YAML or JSON file and supports the full feature set: binds, listeners, routes, backends, and policies. Agentgateway watches the file for changes and applies updates without restarting.Local config translates into an internal representation (IR) shared with XDS. Some fields are remapped for ergonomics — for example, you can specify a backend with a simple host: field and the gateway will resolve it into a full backend definition.See local config structure →

XDS configuration

XDS configuration lets a remote control plane manage the proxy dynamically. Agentgateway uses the XDS Transport Protocol with purpose-built types (not Envoy types).Unlike local config, XDS translation does not fetch from URLs or files — it is optimized for efficiency and direct mapping from control plane to proxy. Resources reference their parents rather than embedding children, keeping update fan-out minimal.Connect to an XDS control plane by setting config.xdsAddress and optionally config.xdsAuthToken in your static config.

Configuration file format

The configuration file supports both YAML and JSON. YAML is recommended for human-authored configs due to its readability and support for comments.

config:
  logging:
    level: info
    format: json

binds:
  - port: 3000
    listeners:
      - routes:
          - backends:
              - mcp:
                  targets:
                    - name: my-server
                      stdio:
                        cmd: npx
                        args: ["@modelcontextprotocol/server-everything"]

Add # yaml-language-server: $schema=https://agentgateway.dev/schema/config at the top of your YAML file to get schema validation and autocompletion in editors that support YAML Language Server.

Specifying the config file

Pass the config file path to the gateway using the -f flag:

agentgateway -f config.yaml

You can also pass configuration as inline bytes directly on the command line for scripting or testing.

Environment variable overrides

Selected static configuration fields can be overridden using environment variables without changing the config file. Environment variables take precedence over file-based settings. For example, the DNS EDNS0 setting can be overridden via:

DNS_EDNS0=true agentgateway -f config.yaml

Environment variable support is field-specific. Check individual field descriptions in the static config reference to see which fields support environment variable overrides.

Dynamic reloading

Agentgateway watches the config file for changes at the filesystem level. When you save an updated file, the gateway reloads local configuration automatically — no restart required. Only local configuration (binds, listeners, routes, backends, policies) is dynamically reloadable. Static configuration fields (logging, worker threads, admin address, etc.) take effect only at startup.

# Edit your config
vim config.yaml

# The gateway detects the change and reloads automatically.
# No restart needed.

Minimal working config

The smallest valid config that proxies MCP traffic needs only a bind, a listener, a route, and a backend:

binds:
  - port: 3000
    listeners:
      - routes:
          - backends:
              - mcp:
                  targets:
                    - name: everything
                      stdio:
                        cmd: npx
                        args: ["@modelcontextprotocol/server-everything"]

Save this as config.yaml and start the gateway:

agentgateway -f config.yaml

The MCP proxy is now available at http://localhost:3000.