For the complete documentation index, see llms.txt. Markdown versions of all docs pages are available by appending .md to any docs URL.
Static configuration
Configure static settings that are applied at startup time.
Most agentgateway configurations dynamically update as you make changes to the gateways, routes, policies, backends, and so on.
However, a few configurations are statically configured at startup. These static configurations are under the config section.
Static configuration file schema
The following table shows the config file schema for static configurations at startup. For the full agentgateway schema of dynamic and static configuration, see the reference docs.
| Field | Type | Description |
|---|---|---|
config | object | config defines top-level settings for DNS, admin, networking, observability, and session management. Unlike other sections, these are applied only at startup and are not dynamically reloaded. |
config.enableIpv6 | boolean | Enable IPv6 address resolution and binding. Defaults to true. |
config.dns | object | DNS resolver settings. |
config.dns.lookupFamily | enum | Controls which IP address families the DNS resolver will query for upstream connections. Accepted values: All, Auto, V4Preferred, V4Only, V6Only. Defaults to Auto (IPv4-only when enableIpv6 is false, both when true). |
config.dns.edns0 | boolean | Whether to enable EDNS0 (Extension Mechanisms for DNS) in the resolver. When None, the system-provided resolver setting is preserved.Can also be set via the DNS_EDNS0 environment variable. |
config.localXdsPath | string | Local XDS path. If not specified, the current configuration file will be used. |
config.modelCatalog | []object | Model cost catalog sources; entries are merged in order, with later entries taking precedence. |
config.modelCatalog[].file | string | Path to a file on disk containing the model cost catalog. |
config.modelCatalog[].inline | string | Model cost catalog provided inline as a string. |
config.modelCatalog[].inline | object | Model cost catalog provided inline as structured data. |
config.modelCatalog[].inline.providers | object | Map of provider name to its supported models and pricing. |
config.modelCatalog[].inline.providers.*.models | object | Map of model ID to its pricing rates and tiers. |
config.modelCatalog[].inline.providers.*.models.*.rates | object | Base pricing rates for this model. |
config.modelCatalog[].inline.providers.*.models.*.rates.input | string | Cost per 1M input (prompt) tokens. |
config.modelCatalog[].inline.providers.*.models.*.rates.output | string | Cost per 1M output (completion) tokens. |
config.modelCatalog[].inline.providers.*.models.*.rates.cacheRead | string | Cost per 1M tokens read from cache. |
config.modelCatalog[].inline.providers.*.models.*.rates.cacheWrite | string | Cost per 1M tokens written to cache. |
config.modelCatalog[].inline.providers.*.models.*.rates.reasoning | string | Cost per 1M reasoning tokens. Falls back to the output rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.rates.inputAudio | string | Cost per 1M input audio tokens. Falls back to the input rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.rates.outputAudio | string | Cost per 1M output audio tokens. Falls back to the output rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.tiers | []object | Context-length pricing tiers that override the base rates. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].contextOver | integer | Context-token threshold above which this tier’s rates apply. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates | object | Pricing rates for this tier, overlaid on the base model rates. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.input | string | Cost per 1M input (prompt) tokens. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.output | string | Cost per 1M output (completion) tokens. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.cacheRead | string | Cost per 1M tokens read from cache. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.cacheWrite | string | Cost per 1M tokens written to cache. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.reasoning | string | Cost per 1M reasoning tokens. Falls back to the output rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.inputAudio | string | Cost per 1M input audio tokens. Falls back to the input rate if unset. |
config.modelCatalog[].inline.providers.*.models.*.tiers[].rates.outputAudio | string | Cost per 1M output audio tokens. Falls back to the output rate if unset. |
config.database | object | Primary database used by local runtime features. |
config.database.url | string | Connection URL for the request log database. A postgres:// or postgresql:// URL uses Postgres; any other value is treated as a SQLite database. |
config.database.maxConnections | integer | Maximum number of connections to open in this database’s connection pool. Defaults to 5. When the request log and config stores have matching database settings, they share one pool with this limit. |
config.storage | object | Controls whether UI-managed configuration is written to the config file or a DB overlay. |
config.storage.mode | enum | Possible values: file, hybrid. |
config.caAddress | string | Address of the Certificate Authority used to issue SPIFFE certificates. |
config.caAuthToken | string | Authentication token for communicating with the Certificate Authority. |
config.xdsAddress | string | Address of the xDS control plane used for dynamic configuration. |
config.xdsAuthToken | string | Authentication token for communicating with the xDS control plane. |
config.namespace | string | Kubernetes namespace for this gateway instance. |
config.gateway | string | Name of this gateway. Re |
config.additionalTrustDomains | string | Comma-separated list of additional SPIFFE trust domains accepted on inbound HBONE connections. The local trust_domain is always implicitly included. |
config.skipValidateTrustDomain | boolean | When true, skip SPIFFE trust-domain verification on inbound HBONE connections. |
config.serviceAccount | string | Kubernetes service account for this gateway, used in its SPIFFE identity. |
config.clusterId | string | Identifier for the cluster this gateway runs in. Defaults to “Kubernetes”. |
config.network | string | Network name for this gateway, used for locality-aware routing. |
config.adminAddr | string | Admin UI address in the format “ip:port”, “localhost:port”, “unix:/path/to/socket”, or “off” |
config.standardAttributes | object | Standard request log attributes populated for database-backed local runtime features. |
config.standardAttributes.user | string | CEL expression used to populate the agentgateway.user request log attribute. |
config.standardAttributes.group | string | CEL expression used to populate the agentgateway.group request log attribute. |
config.statsAddr | string | Stats/metrics server address in the format “ip:port”, “localhost:port”, “unix:/path/to/socket”, or “off” |
config.readinessAddr | string | Readiness probe server address in the format “ip:port”, “localhost:port”, “unix:/path/to/socket”, or “off” |
config.session | object | Configuration for stateful session management |
config.session.key | string | The AES-256-GCM session protection key to be used for session tokens. If not set, sessions will not be encrypted. For example, generated via openssl rand -hex 32. |
| `config | `config | config.customFunctions |
config.connectionTerminationDeadline | string | Maximum time to wait for connections to close gracefully during shutdown. |
config.connectionMinTerminationDeadline | string | Minimum time to allow for graceful connection termination. Defaults to zero. |
config.workerThreads | string | Number of worker threads for the async runtime. Accepts a number or a string such as “auto”. |
config.tracing | object | Distributed tracing configuration. |
config.tracing.otlpEndpoint | string | OTLP collector endpoint URL for exporting traces. |
config.tracing.headers | object | HTTP headers to include on OTLP trace exports, such as authentication headers. |
config.tracing.otlpProtocol | enum | OTLP transport protocol: grpc or http.Possible values: grpc, http. |
config.tracing.fields | object | Custom fields to add to or remove from trace spans. |
config.tracing.fields.remove | []string | Field names to remove from log entries. |
config.tracing.fields.add | object | Map of field name to a CEL expression that computes the value to add to logs. |
config.tracing.randomSampling | string | Expression to determine the amount of random sampling. Random sampling will initiate a new trace span if the incoming request does not have a trace already. This should evaluate to either a float between 0.0-1.0 (0-100%) or true/false. This defaults to ‘false’. |
config.tracing.clientSampling | string | Expression to determine the amount of client sampling. Client sampling determines whether to initiate a new trace span if the incoming request does have a trace already. This should evaluate to either a float between 0.0-1.0 (0-100%) or true/false. This defaults to ’true'. |
config.tracing.path | string | OTLP path. Default is /v1/traces |
config.logging | object | Logging configuration, including filter, level, format, and custom fields. |
config.logging.filter | string | CEL expression that selects which requests are logged. |
config.logging.fields | object | Custom fields to add to or remove from log entries. |
config.logging.fields.remove | []string | Field names to remove from log entries. |
config.logging.fields.add | object | Map of field name to a CEL expression that computes the value to add to logs. |
config.logging.level | string | Log level: a single level (e.g. info), a comma-separated string of per-module levels (e.g. info,agent_core=trace), or a list of per-module levels (e.g. [info, agent_core=trace]). |
config.logging.format | enum | Log output format: text or json.Possible values: text, json, null. |
config.logging.database | object | Log-store database configuration; enables request logging to a database backend. |
config.logging.database.url | string | Connection URL for the request log database. A postgres:// or postgresql:// URL uses Postgres; any other value is treated as a SQLite database. |
config.logging.database.maxConnections | integer | Maximum number of connections to open in this database’s connection pool. Defaults to 5. When the request log and config stores have matching database settings, they share one pool with this limit. |
config.metrics | object | Metrics configuration, including metric removal and custom fields. |
config.metrics.remove | []string | Metric names to exclude from collection. |
config.metrics.fields | object | Custom fields to add to all metrics. |
config.metrics.fields.add | object | Map of field name to a CEL expression that computes the value to add to metrics. |
config.backend | object | Configuration for upstream connections, including keepalives, timeouts, and pooling. |
config.backend.keepalives | object | TCP keepalive configuration for upstream connections. |
config.backend.keepalives.enabled | boolean | Enable TCP keepalive probes on backend connections. Defaults to true. |
config.backend.keepalives.time | string | Idle time before the first keepalive probe is sent. |
config.backend.keepalives.interval | string | Time between successive keepalive probes. |
config.backend.keepalives.retries | integer | Number of unacknowledged probes before the connection is considered dead. |
config.backend.connectTimeout | string | Maximum time to wait when establishing a connection to an upstream. Defaults to 10 seconds. |
config.backend.poolIdleTimeout | string | The maximum duration to keep an idle connection alive. |
config.backend.poolMaxSize | integer | The maximum number of connections allowed in the pool, per hostname. If set, this will limit the total number of connections kept alive to any given host. Note: excess connections will still be created, they will just not remain idle. If unset, there is no limit |
config.hbone | object | HBONE (HTTP/2 CONNECT tunnel) protocol configuration. |
config.hbone.windowSize | integer | HTTP/2 per-stream flow-control window size in bytes. Defaults to 4 MiB. |
config.hbone.connectionWindowSize | integer | HTTP/2 connection-level flow-control window size in bytes. Defaults to 16 MiB. |
config.hbone.frameSize | integer | HTTP/2 maximum frame size in bytes. Defaults to 1 MiB. |
config.hbone.poolMaxStreamsPerConn | integer | Maximum concurrent streams per pooled connection. Defaults to 100. |
config.hbone.poolUnusedReleaseTimeout | string | Duration after which unused pooled connections are released. |
Was this page helpful?
