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

# Static configuration

> All fields under the config key — global settings read once at startup including logging, tracing, DNS, sessions, and XDS.

Static configuration lives under the top-level `config` key in your YAML or JSON file. These fields are read exactly once when the process starts. Changing them requires a restart — they are not dynamically reloaded.

```yaml theme={null}
config:
  adminAddr: "0.0.0.0:15000"
  statsAddr: "0.0.0.0:15020"
  readinessAddr: "0.0.0.0:15021"
  workerThreads: 4
  logging:
    level: info
    format: json
  tracing:
    otlpEndpoint: http://otel-collector:4317
    randomSampling: "0.1"
  dns:
    lookupFamily: Auto
```

## Top-level fields

<ParamField path="config.adminAddr" type="string">
  Address for the admin UI server in `ip:port` format. The admin interface exposes runtime diagnostics and configuration inspection.

  Example: `"0.0.0.0:15000"`
</ParamField>

<ParamField path="config.statsAddr" type="string">
  Address for the stats and metrics server in `ip:port` format. Exposes Prometheus-compatible metrics.

  Example: `"0.0.0.0:15020"`
</ParamField>

<ParamField path="config.readinessAddr" type="string">
  Address for the readiness probe server in `ip:port` format. Returns HTTP 200 when the gateway is ready to serve traffic.

  Example: `"0.0.0.0:15021"`
</ParamField>

<ParamField path="config.workerThreads" type="number">
  Number of worker threads for handling requests. Defaults to the number of logical CPUs when not set.
</ParamField>

<ParamField path="config.enableIpv6" type="boolean">
  Enable IPv6 support. When `true`, the DNS resolver defaults to querying both IPv4 and IPv6 address families. See also `config.dns.lookupFamily`.
</ParamField>

<ParamField path="config.localXdsPath" type="string">
  Override the path used for local XDS configuration. When not set, the current configuration file is used as the local XDS source.
</ParamField>

<ParamField path="config.connectionTerminationDeadline" type="string">
  Maximum time to wait for in-flight connections to finish draining on shutdown.
</ParamField>

<ParamField path="config.connectionMinTerminationDeadline" type="string">
  Minimum time to wait before forcing connection termination during shutdown.
</ParamField>

## DNS settings

<ParamField path="config.dns" type="object">
  DNS resolver configuration.

  <Expandable title="config.dns fields">
    <ParamField path="config.dns.lookupFamily" type="string">
      Controls which IP address families the DNS resolver queries for upstream connections.

      Accepted values:

      * `Auto` — IPv4 only when `enableIpv6` is false, both when true. **Default.**
      * `All` — Query both IPv4 and IPv6.
      * `V4Preferred` — Prefer IPv4, fall back to IPv6.
      * `V4Only` — Only query IPv4.
      * `V6Only` — Only query IPv6.
    </ParamField>

    <ParamField path="config.dns.edns0" type="boolean">
      Whether to enable EDNS0 (Extension Mechanisms for DNS) in the resolver. When not set, the system-provided resolver setting is preserved.

      Can also be set via the `DNS_EDNS0` environment variable.
    </ParamField>
  </Expandable>
</ParamField>

## Session management

<ParamField path="config.session" type="object">
  Configuration for stateful session management.

  <Expandable title="config.session fields">
    <ParamField path="config.session.key" type="string">
      The AES-256-GCM key used to encrypt and sign session tokens. When not set, sessions are not encrypted.

      Generate a key with:

      ```bash theme={null}
      openssl rand -hex 32
      ```

      <Warning>
        Keep this value secret. Anyone with this key can forge valid session tokens.
      </Warning>
    </ParamField>
  </Expandable>
</ParamField>

## Logging

<ParamField path="config.logging" type="object">
  Controls log output format, verbosity, and field customization.

  <Expandable title="config.logging fields">
    <ParamField path="config.logging.level" type="string">
      Minimum log level to emit. Accepted values: `trace`, `debug`, `info`, `warn`, `error`.

      Defaults to `info`.
    </ParamField>

    <ParamField path="config.logging.format" type="string">
      Log output format. Accepted values:

      * `text` — Human-readable format. **Default.**
      * `json` — Structured JSON, suitable for log aggregation pipelines.
    </ParamField>

    <ParamField path="config.logging.filter" type="string">
      Fine-grained log filter expression. Follows the `tracing` crate's filter directive syntax, allowing per-module level control.

      Example: `"agentgateway=debug,tower=warn"`
    </ParamField>

    <ParamField path="config.logging.fields" type="object">
      Customize the fields included in each log entry.

      <Expandable title="config.logging.fields">
        <ParamField path="config.logging.fields.remove" type="string[]">
          List of field names to remove from log output.
        </ParamField>

        <ParamField path="config.logging.fields.add" type="object">
          Key-value pairs to add as static fields to every log entry.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

**Example:**

```yaml theme={null}
config:
  logging:
    level: debug
    format: json
    filter: "agentgateway=debug,tower=info"
    fields:
      add:
        environment: production
        region: us-east-1
      remove:
        - thread_id
```

## Tracing

Agentgateway supports distributed tracing via OpenTelemetry. Configure the OTLP exporter and sampling behavior under `config.tracing`.

<ParamField path="config.tracing" type="object">
  OpenTelemetry tracing configuration.

  <Expandable title="config.tracing fields">
    <ParamField path="config.tracing.otlpEndpoint" type="string">
      The OTLP exporter endpoint to send traces to.

      Example: `"http://otel-collector:4317"`
    </ParamField>

    <ParamField path="config.tracing.otlpProtocol" type="string">
      The OTLP transport protocol. Accepted values: `grpc`, `http/protobuf`, `http/json`.
    </ParamField>

    <ParamField path="config.tracing.path" type="string">
      OTLP HTTP path for trace export. Defaults to `/v1/traces`.
    </ParamField>

    <ParamField path="config.tracing.randomSampling" type="string">
      Controls random sampling — whether to start a new trace span when the incoming request does **not** already carry a trace.

      Accepts a float between `0.0` and `1.0` (representing 0–100%) or `true`/`false`.

      Defaults to `false` (no new traces initiated for untraced requests).
    </ParamField>

    <ParamField path="config.tracing.clientSampling" type="string">
      Controls client sampling — whether to start a new trace span when the incoming request **does** already carry a trace.

      Accepts a float between `0.0` and `1.0` or `true`/`false`.

      Defaults to `true` (always propagate existing traces).
    </ParamField>

    <ParamField path="config.tracing.headers" type="object">
      Additional HTTP headers to send with OTLP export requests. Useful for authentication with managed observability backends.
    </ParamField>

    <ParamField path="config.tracing.fields" type="object">
      Customize trace span attributes.

      <Expandable title="config.tracing.fields">
        <ParamField path="config.tracing.fields.remove" type="string[]">
          Attribute names to remove from all spans.
        </ParamField>

        <ParamField path="config.tracing.fields.add" type="object">
          Static key-value attributes to add to all spans.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

**Example:**

```yaml theme={null}
config:
  tracing:
    otlpEndpoint: http://otel-collector:4317
    otlpProtocol: grpc
    randomSampling: "0.1"
    clientSampling: "true"
    fields:
      add:
        deployment.environment: production
```

## Metrics

<ParamField path="config.metrics" type="object">
  Prometheus metrics configuration.

  <Expandable title="config.metrics fields">
    <ParamField path="config.metrics.remove" type="string[]">
      Names of metric series to remove from the metrics output entirely.
    </ParamField>

    <ParamField path="config.metrics.fields" type="object">
      Customize metric label fields.

      <Expandable title="config.metrics.fields">
        <ParamField path="config.metrics.fields.add" type="object">
          Static label key-value pairs to attach to all metrics.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

## Backend connection pooling

These settings control how the gateway manages TCP connections to upstream backends.

<ParamField path="config.backend" type="object">
  Global backend connection settings.

  <Expandable title="config.backend fields">
    <ParamField path="config.backend.connectTimeout" type="string">
      Maximum time to wait when establishing a new connection to an upstream backend. Formatted as a duration string.

      Example: `"10s"`
    </ParamField>

    <ParamField path="config.backend.poolIdleTimeout" type="string">
      Maximum duration to keep an idle connection alive in the pool before closing it.
    </ParamField>

    <ParamField path="config.backend.poolMaxSize" type="number">
      Maximum number of connections kept in the pool per hostname. Excess connections are still created when needed but are not pooled after use. When not set, there is no limit.
    </ParamField>

    <ParamField path="config.backend.keepalives" type="object">
      TCP keepalive settings for backend connections.

      <Expandable title="config.backend.keepalives fields">
        <ParamField path="config.backend.keepalives.enabled" type="boolean">
          Enable TCP keepalives on backend connections.
        </ParamField>

        <ParamField path="config.backend.keepalives.time" type="string">
          Time a connection must be idle before sending the first keepalive probe.
        </ParamField>

        <ParamField path="config.backend.keepalives.interval" type="string">
          Time between successive keepalive probes.
        </ParamField>

        <ParamField path="config.backend.keepalives.retries" type="number">
          Number of failed keepalive probes before the connection is declared dead.
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

**Example:**

```yaml theme={null}
config:
  backend:
    connectTimeout: 10s
    poolIdleTimeout: 90s
    poolMaxSize: 100
    keepalives:
      enabled: true
      time: 30s
      interval: 5s
      retries: 3
```

## HBONE settings

HBONE (HTTP-Based Overlay Network Encapsulation) is used for encrypted tunneling between proxies.

<ParamField path="config.hbone" type="object">
  HBONE HTTP/2 tunnel settings.

  <Expandable title="config.hbone fields">
    <ParamField path="config.hbone.windowSize" type="number">
      HTTP/2 stream-level flow control window size in bytes.
    </ParamField>

    <ParamField path="config.hbone.connectionWindowSize" type="number">
      HTTP/2 connection-level flow control window size in bytes.
    </ParamField>

    <ParamField path="config.hbone.frameSize" type="number">
      Maximum HTTP/2 frame size in bytes.
    </ParamField>

    <ParamField path="config.hbone.poolMaxStreamsPerConn" type="number">
      Maximum number of concurrent HTTP/2 streams per HBONE connection.
    </ParamField>

    <ParamField path="config.hbone.poolUnusedReleaseTimeout" type="string">
      How long to wait before releasing an unused HBONE connection from the pool.
    </ParamField>
  </Expandable>
</ParamField>

## XDS control plane connection

Connect Agentgateway to a remote XDS control plane for centralized dynamic configuration.

<ParamField path="config.xdsAddress" type="string">
  Address of the XDS control plane server.

  Example: `"grpc://xds-server:15010"`
</ParamField>

<ParamField path="config.xdsAuthToken" type="string">
  Authentication token sent to the XDS server.
</ParamField>

<ParamField path="config.caAddress" type="string">
  Address of the certificate authority (CA) server for mTLS certificate issuance.
</ParamField>

<ParamField path="config.caAuthToken" type="string">
  Authentication token for the CA server.
</ParamField>

<ParamField path="config.namespace" type="string">
  Kubernetes namespace the gateway is running in. Used by the XDS and CA integrations.
</ParamField>

<ParamField path="config.serviceAccount" type="string">
  Kubernetes service account name. Used for identity in XDS and CA requests.
</ParamField>

<ParamField path="config.trustDomain" type="string">
  SPIFFE trust domain for workload identity.
</ParamField>

<ParamField path="config.clusterId" type="string">
  Cluster identifier reported to the XDS control plane.
</ParamField>

<ParamField path="config.network" type="string">
  Network identifier reported to the XDS control plane.
</ParamField>

<ParamField path="config.gateway" type="string">
  Gateway name reported to the XDS control plane.
</ParamField>

**Example — connecting to an XDS control plane:**

```yaml theme={null}
config:
  xdsAddress: grpc://xds-server:15010
  xdsAuthToken: my-secret-token
  caAddress: grpc://istiod:15012
  namespace: default
  serviceAccount: agentgateway
  trustDomain: cluster.local
  clusterId: my-cluster
```