> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/agentgateway/agentgateway/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration reference overview

> Understand how Agentgateway's three-layer configuration system works, and where each setting belongs.

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

<AccordionGroup>
  <Accordion title="Static configuration" icon="lock" defaultOpen={true}>
    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 →](/reference/static-config)
  </Accordion>

  <Accordion title="Local configuration" icon="file-code">
    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 →](/reference/local-config)
  </Accordion>

  <Accordion title="XDS configuration" icon="cloud">
    XDS configuration lets a remote control plane manage the proxy dynamically. Agentgateway uses the [XDS Transport Protocol](https://www.envoyproxy.io/docs/envoy/latest/api-docs/xds_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.
  </Accordion>
</AccordionGroup>

## 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.

<CodeGroup>
  ```yaml config.yaml theme={null}
  config:
    logging:
      level: info
      format: json

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

  ```json config.json theme={null}
  {
    "config": {
      "logging": {
        "level": "info",
        "format": "json"
      }
    },
    "binds": [
      {
        "port": 3000,
        "listeners": [
          {
            "routes": [
              {
                "backends": [
                  {
                    "mcp": {
                      "targets": [
                        {
                          "name": "my-server",
                          "stdio": {
                            "cmd": "npx",
                            "args": ["@modelcontextprotocol/server-everything"]
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
  ```
</CodeGroup>

<Tip>
  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.
</Tip>

## Specifying the config file

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

```bash theme={null}
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:

```bash theme={null}
DNS_EDNS0=true agentgateway -f config.yaml
```

<Note>
  Environment variable support is field-specific. Check individual field descriptions in the [static config reference](/reference/static-config) to see which fields support environment variable overrides.
</Note>

## 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.

```bash theme={null}
# 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:

```yaml theme={null}
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:

```bash theme={null}
agentgateway -f config.yaml
```

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

## Configuration reference

<CardGroup cols={2}>
  <Card title="Static config" icon="sliders" href="/reference/static-config">
    Global settings: logging, tracing, DNS, session keys, admin ports, and XDS connection.
  </Card>

  <Card title="Local config" icon="file-code" href="/reference/local-config">
    Runtime configuration: binds, listeners, routes, backends, and policies.
  </Card>

  <Card title="Binds" icon="ethernet" href="/reference/binds">
    Port bindings — the entry points for all incoming traffic.
  </Card>

  <Card title="Listeners" icon="ear" href="/reference/listeners">
    Virtual hosts, protocols, and TLS settings per port.
  </Card>

  <Card title="Routes" icon="route" href="/reference/routes">
    Traffic matching rules that connect listeners to backends.
  </Card>

  <Card title="Backends" icon="server" href="/reference/backends">
    Upstream MCP servers, A2A agents, and HTTP services.
  </Card>
</CardGroup>