Static configuration
Most agentgateway configurations dynamically update as you make changes to the binds, 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.enableIpv6 | boolean | |
config.dns | object | DNS resolver settings. |
config.dns.lookupFamily | string | 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.caAddress | string | |
config.caAuthToken | string | |
config.xdsAddress | string | |
config.xdsAuthToken | string | |
config.namespace | string | |
config.gateway | string | |
config.trustDomain | string | |
config.serviceAccount | string | |
config.clusterId | string | |
config.network | string | |
config.adminAddr | string | Admin UI address in the format “ip:port” |
config.statsAddr | string | Stats/metrics server address in the format “ip:port” |
config.readinessAddr | string | Readiness probe server address in the format “ip:port” |
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.connectionTerminationDeadline | string | |
config.connectionMinTerminationDeadline | string | |
config.workerThreads | string | |
config.tracing | object | |
config.tracing.otlpEndpoint | string | |
config.tracing.headers | object | |
config.tracing.otlpProtocol | string | |
config.tracing.fields | object | |
config.tracing.fields.remove | []string | |
config.tracing.fields.add | object | |
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 | |
config.logging.filter | string | |
config.logging.fields | object | |
config.logging.fields.remove | []string | |
config.logging.fields.add | object | |
config.logging.level | string | |
config.logging.format | string | |
config.metrics | object | |
config.metrics.remove | []string | |
config.metrics.fields | object | |
config.metrics.fields.add | object | |
config.backend | object | |
config.backend.keepalives | object | |
config.backend.keepalives.enabled | boolean | |
config.backend.keepalives.time | string | |
config.backend.keepalives.interval | string | |
config.backend.keepalives.retries | integer | |
config.backend.connectTimeout | string | |
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 | |
config.hbone.windowSize | integer | |
config.hbone.connectionWindowSize | integer | |
config.hbone.frameSize | integer | |
config.hbone.poolMaxStreamsPerConn | integer | |
config.hbone.poolUnusedReleaseTimeout | string | |
llm.port | integer | |
llm.models | []object | models defines the set of models that can be served by this gateway. The model name refers to the model in the users request that is matched; the model sent to the actual LLM can be overridden on a per-model basis. |
llm.models[].name | string | name is the name of the model we are matching from a users request. If params.model is set, that will be used in the request to the LLM provider. If not, the incoming model is used. |
llm.models[].params | object | params customizes parameters for the outgoing request |
llm.models[].params.model | string | The model to send to the provider. If unset, the same model will be used from the request. |
llm.models[].params.apiKey | object | An API key to attach to the request. If unset this will be automatically detected from the environment. |
llm.models[].params.apiKey.file | string | |
llm.models[].params.awsRegion | string | |
llm.models[].params.vertexRegion | string | |
llm.models[].params.vertexProject | string | |
llm.models[].params.azureHost | string | For Azure: the host of the deployment |
llm.models[].params.azureApiVersion | string | For Azure: the API version to use |
llm.models[].params.hostOverride | string | Override the upstream host for this provider. |
llm.models[].params.pathOverride | string | Override the upstream path for this provider. |
llm.models[].params.tokenize | boolean | Whether to tokenize the request before forwarding it upstream. |
llm.models[].provider | string | provider of the LLM we are connecting too |
llm.models[].defaults | object | defaults allows setting default values for the request. If these are not present in the request body, they will be set. To override even when set, use overrides. |
llm.models[].overrides | object | overrides allows setting values for the request, overriding any existing values |
llm.models[].transformation | object | transformation allows setting values from CEL expressions for the request, overriding any existing values. |
llm.models[].requestHeaders | object | requestHeaders modifies headers in requests to the LLM provider. |
llm.models[].requestHeaders.add | object | |
llm.models[].requestHeaders.set | object | |
llm.models[].requestHeaders.remove | []string | |
llm.models[].responseHeaders | object | responseHeaders modifies headers in responses from the LLM provider. |
llm.models[].responseHeaders.add | object | |
llm.models[].responseHeaders.set | object | |
llm.models[].responseHeaders.remove | []string | |
llm.models[].backendTLS | object | backendTLS configures TLS when connecting to the LLM provider. |
llm.models[].backendTLS.cert | string | |
llm.models[].backendTLS.key | string | |
llm.models[].backendTLS.root | string | |
llm.models[].backendTLS.hostname | string | |
llm.models[].backendTLS.insecure | boolean | |
llm.models[].backendTLS.insecureHost | boolean | |
llm.models[].backendTLS.alpn | []string | |
llm.models[].backendTLS.subjectAltNames | []string | |
llm.models[].health | object | health configures outlier detection for this model backend. |
llm.models[].health.unhealthyExpression | string | CEL expression; true means unhealthy (evict). E.g. response.code >= 500.When unset, any 5xx or connection failure is treated as unhealthy. |
llm.models[].health.eviction | object | Local/config eviction sub-policy with duration as string; mirrors Eviction. |
llm.models[].health.eviction.duration | string | |
llm.models[].health.eviction.restoreHealth | number | |
llm.models[].health.eviction.consecutiveFailures | integer | |
llm.models[].health.eviction.healthThreshold | number | |
llm.models[].backendTunnel | object | backendTunnel configures tunneling when connecting to the LLM provider. |
llm.models[].backendTunnel.proxy | object | Reference to the proxy address Exactly one of service, host, or backend may be set. |
llm.models[].backendTunnel.proxy.service | object | |
llm.models[].backendTunnel.proxy.service.name | object | |
llm.models[].backendTunnel.proxy.service.name.namespace | string | |
llm.models[].backendTunnel.proxy.service.name.hostname | string | |
llm.models[].backendTunnel.proxy.service.port | integer | |
llm.models[].backendTunnel.proxy.host | string | Hostname or IP address |
llm.models[].backendTunnel.proxy.backend | string | Explicit backend reference. Backend must be defined in the top level |
llm.models[].guardrails.request | []object | |
llm.models[].guardrails.request[].regex | object | |
llm.models[].guardrails.request[].regex.action | string | |
llm.models[].guardrails.request[].regex.rules | []object | |
llm.models[].guardrails.request[].regex.rules[].builtin | string | |
llm.models[].guardrails.request[].regex.rules[].pattern | string | |
llm.models[].guardrails.request[].webhook | object | |
llm.models[].guardrails.request[].webhook.target | object | Exactly one of service, host, or backend may be set. |
llm.models[].guardrails.request[].webhook.target.service | object | |
llm.models[].guardrails.request[].webhook.target.service.name | object | |
llm.models[].guardrails.request[].webhook.target.service.name.namespace | string | |
llm.models[].guardrails.request[].webhook.target.service.name.hostname | string | |
llm.models[].guardrails.request[].webhook.target.service.port | integer | |
llm.models[].guardrails.request[].webhook.target.host | string | Hostname or IP address |
llm.models[].guardrails.request[].webhook.target.backend | string | Explicit backend reference. Backend must be defined in the top level |
llm.models[].guardrails.request[].webhook.forwardHeaderMatches[].name | string | |
llm.models[].guardrails.request[].webhook.forwardHeaderMatches[].value | object | Exactly one of exact or regex may be set. |
llm.models[].guardrails.request[].webhook.forwardHeaderMatches[].value.exact | string | |
llm.models[].guardrails.request[].webhook.forwardHeaderMatches[].value.regex | string | |
llm.models[].guardrails.request[].openAIModeration | object | |
llm.models[].guardrails.request[].openAIModeration.model | string | Model to use. Defaults to omni-moderation-latest |
| `llm.models[].guardrails.request[].openAIModeration | `llm.models[].guardrails.request[].openAIModeration | `llm.models[].guardrails.request[].openAIModeration |
llm.models[].guardrails.request[].bedrockGuardrails.guardrailIdentifier | string | The unique identifier of the guardrail |
llm.models[].guardrails.request[].bedrockGuardrails.guardrailVersion | string | The version of the guardrail |
llm.models[].guardrails.request[].bedrockGuardrails.region | string | AWS region where the guardrail is deployed |
| `llm.models[].guardrails.request[].bedrockGuardrails | `llm.models[].guardrails.request[].bedrockGuardrails | `llm.models[].guardrails.request[].bedrockGuardrails |
llm.models[].guardrails.request[].googleModelArmor.templateId | string | The template ID for the Model Armor configuration |
llm.models[].guardrails.request[].googleModelArmor.projectId | string | The GCP project ID |
llm.models[].guardrails.request[].googleModelArmor.location | string | The GCP region (default: us-central1) |
| `llm.models[].guardrails.request[].googleModelArmor | `llm.models[].guardrails.request[].googleModelArmor | `llm.models[].guardrails.request[].googleModelArmor |
llm.models[].guardrails.request[].rejection.body | array | |
llm.models[].guardrails.request[].rejection.status | integer | |
llm.models[].guardrails.request[].rejection.headers | object | Optional headers to add, set, or remove from the rejection response |
llm.models[].guardrails.request[].rejection.headers.add | object | |
llm.models[].guardrails.request[].rejection.headers.set | object | |
llm.models[].guardrails.request[].rejection.headers.remove | []string | |
llm.models[].guardrails.response | []object | |
llm.models[].guardrails.response[].regex | object | |
llm.models[].guardrails.response[].regex.action | string | |
llm.models[].guardrails.response[].regex.rules | []object | |
llm.models[].guardrails.response[].regex.rules[].builtin | string | |
llm.models[].guardrails.response[].regex.rules[].pattern | string | |
llm.models[].guardrails.response[].webhook | object | |
llm.models[].guardrails.response[].webhook.target | object | Exactly one of service, host, or backend may be set. |
llm.models[].guardrails.response[].webhook.target.service | object | |
llm.models[].guardrails.response[].webhook.target.service.name | object | |
llm.models[].guardrails.response[].webhook.target.service.name.namespace | string | |
llm.models[].guardrails.response[].webhook.target.service.name.hostname | string | |
llm.models[].guardrails.response[].webhook.target.service.port | integer | |
llm.models[].guardrails.response[].webhook.target.host | string | Hostname or IP address |
llm.models[].guardrails.response[].webhook.target.backend | string | Explicit backend reference. Backend must be defined in the top level |
llm.models[].guardrails.response[].webhook.forwardHeaderMatches[].name | string | |
llm.models[].guardrails.response[].webhook.forwardHeaderMatches[].value | object | Exactly one of exact or regex may be set. |
llm.models[].guardrails.response[].webhook.forwardHeaderMatches[].value.exact | string | |
llm.models[].guardrails.response[].webhook.forwardHeaderMatches[].value.regex | string | |
llm.models[].guardrails.response[].bedrockGuardrails | object | Configuration for AWS Bedrock Guardrails integration. |
llm.models[].guardrails.response[].bedrockGuardrails.guardrailIdentifier | string | The unique identifier of the guardrail |
llm.models[].guardrails.response[].bedrockGuardrails.guardrailVersion | string | The version of the guardrail |
llm.models[].guardrails.response[].bedrockGuardrails.region | string | AWS region where the guardrail is deployed |
| `llm.models[].guardrails.response[].bedrockGuardrails | `llm.models[].guardrails.response[].bedrockGuardrails | `llm.models[].guardrails.response[].bedrockGuardrails |
llm.models[].guardrails.response[].googleModelArmor.templateId | string | The template ID for the Model Armor configuration |
llm.models[].guardrails.response[].googleModelArmor.projectId | string | The GCP project ID |
llm.models[].guardrails.response[].googleModelArmor.location | string | The GCP region (default: us-central1) |
| `llm.models[].guardrails.response[].googleModelArmor | `llm.models[].guardrails.response[].googleModelArmor | `llm.models[].guardrails.response[].googleModelArmor |
llm.models[].guardrails.response[].rejection.body | array | |
llm.models[].guardrails.response[].rejection.status | integer | |
llm.models[].guardrails.response[].rejection.headers | object | Optional headers to add, set, or remove from the rejection response |
llm.models[].guardrails.response[].rejection.headers.add | object | |
llm.models[].guardrails.response[].rejection.headers.set | object | |
llm.models[].guardrails.response[].rejection.headers.remove | []string | |
llm.models[].matches | []object | matches specifies the conditions under which this model should be used in addition to matching the model name. |
llm.models[].matches[].headers | []object | |
llm.models[].matches[].headers[].name | string | |
llm.models[].matches[].headers[].value | object | Exactly one of exact or regex may be set. |
llm.models[].matches[].headers[].value.exact | string | |
llm.models[].matches[].headers[].value.regex | string | |
| `llm | `llm | `llm |
mcp.port | integer | |
mcp.targets | []object | |
mcp.targets[].sse | object | |
mcp.targets[].sse.host | string | |
mcp.targets[].sse.port | integer | |
mcp.targets[].sse.path | string | |
mcp.targets[].mcp | object | |
mcp.targets[].mcp.host | string | |
mcp.targets[].mcp.port | integer | |
mcp.targets[].mcp.path | string | |
mcp.targets[].stdio | object | |
mcp.targets[].stdio.cmd | string | |
mcp.targets[].stdio.args | []string | |
mcp.targets[].stdio.env | object | |
mcp.targets[].openapi | object | |
mcp.targets[].openapi.host | string | |
mcp.targets[].openapi.port | integer | |
mcp.targets[].openapi.path | string | |
mcp.targets[].openapi.schema | object | |
mcp.targets[].openapi.schema.file | string | |
mcp.targets[].openapi.schema.url | string | |
mcp.targets[].name | string | |
| `mcp.targets[] | `mcp.targets[] | `mcp.targets[] |
mcp.prefixMode | string | |
mcp.failureMode | string | Behavior when one or more MCP targets fail to initialize or fail during fanout. Defaults to failClosed. |
| `mcp | `mcp | `mcp |
