Configuration Files

AISIX AI Gateway uses a startup configuration file to define process-level settings such as listeners, etcd connectivity, TLS, observability, cache and rate-limit backends, and managed-gateway startup.

Models, caller API keys, provider keys, guardrails, cache policies, and observability exporters are not defined in the startup configuration. They are stored in etcd and managed through the Admin API or the AISIX managed control plane.

AISIX accepts YAML, TOML, or JSON startup configuration files. Common files include:

• config.yaml: the local startup configuration file loaded by AISIX.
• config.example.yaml: a complete self-hosted example that you can copy or mount as the loaded config.yaml.
• config.managed.yaml: the managed data-plane bootstrap configuration used when the control plane supplies settings at runtime.

The examples below use YAML because the packaged example configurations use YAML. TOML and JSON files can define the same startup fields.

Common Startup Configuration

The following self-hosted example uses etcd and shows common startup settings.

config.yaml

etcd:
  endpoints:                          # etcd endpoints used to store dynamic gateway resources.
    - "http://127.0.0.1:2379"
  prefix: "/aisix"                    # Key prefix used by AISIX in etcd.
  # env_id: "ENVIRONMENT_ID"          # Optional environment scope for self-hosted etcd keys.
  # user: "aisix"                     # Optional etcd username.
  # password_env: "AISIX_ETCD_PASSWORD" # Environment variable containing the etcd password.
  dial_timeout_ms: 5000               # Timeout for establishing an etcd connection.
  request_timeout_ms: 5000            # Timeout for etcd requests.
  # tls:                              # mTLS settings; all three certificate fields are required together.
  #   ca_cert_file: "/etc/aisix/mtls/ca.crt"
  #   client_cert_file: "/etc/aisix/mtls/client.crt"
  #   client_key_file: "/etc/aisix/mtls/client.key"
  #   domain_name: "etcd.example.com" # Optional SNI and certificate-name override.

proxy:
  addr: "0.0.0.0:3000"                # Address for caller-facing proxy APIs.
  request_body_limit_bytes: 10485760  # Maximum request body size. The example value is 10 MiB.
  # tls:                              # HTTPS certificate and key for the proxy listener.
  #   cert_file: "/etc/aisix/tls/proxy.crt"
  #   key_file: "/etc/aisix/tls/proxy.key"
  # real_ip:                          # Caller IP resolution when AISIX runs behind trusted proxies.
  #   trusted_proxies:
  #     - "10.0.0.0/8"
  #   recursive: true
  #   header: "x-forwarded-for"

admin:
  addr: "127.0.0.1:3001"              # Address for the Admin API.
  admin_keys:                         # Keys allowed to call the Admin API.
    - "YOUR_ADMIN_KEY"
  # tls:                              # HTTPS certificate and key for the admin listener.
  #   cert_file: "/etc/aisix/tls/admin.crt"
  #   key_file: "/etc/aisix/tls/admin.key"

observability:
  service_name: "aisix"               # Service name used in telemetry.
  log_level: "info"                   # Process log level.
  access_log: true                    # Whether to emit access logs.
  metrics:
    prometheus:
      enabled: true                   # Whether to expose Prometheus metrics.
      path: "/metrics"                # Metrics endpoint path.
      addr: "0.0.0.0:9090"            # Dedicated metrics/status listener address.
    otlp:
      enabled: false                  # Reserved startup OTLP metrics settings.
      endpoint: "http://127.0.0.1:4317"
  tracing:
    otlp:
      enabled: false                  # Reserved startup OTLP tracing settings.
      endpoint: "http://127.0.0.1:4317"
      sample_ratio: 1.0

# managed:                            # Enable when this gateway uses the AISIX managed control plane.
#   enabled: true

cache:
  backend: "memory"                   # Legacy compatibility knob. Cache policies choose the runtime backend.
  # redis:                            # Redis connection used by cache policies that select Redis.
  #   mode: "single"
  #   url: "redis://127.0.0.1:6379"
  #   # nodes: ["redis://10.0.0.1:6379"]        # Cluster mode seed nodes.
  #   # sentinels: ["redis://10.0.0.1:26379"]   # Sentinel mode nodes.
  #   # master_name: "mymaster"                  # Sentinel mode master group.
  #   # username: "default"                      # Cluster or Sentinel data-node ACL user.
  #   # password: "replace-me"                   # Cluster or Sentinel data-node ACL password.
  #   # database: 0                              # Sentinel master database index.
  #   # For single mode, put credentials in the Redis URL.

ratelimit:
  backend: "memory"                   # Rate-limit counter backend. Use redis for shared counters across replicas.
  # redis:
  #   mode: "single"
  #   url: "redis://127.0.0.1:6379"
  #   # nodes: ["redis://10.0.0.1:6379"]        # Cluster mode seed nodes.
  #   # sentinels: ["redis://10.0.0.1:26379"]   # Sentinel mode nodes.
  #   # master_name: "mymaster"                  # Sentinel mode master group.
  #   # username: "default"                      # Cluster or Sentinel data-node ACL user.
  #   # password: "replace-me"                   # Cluster or Sentinel data-node ACL password.
  #   # database: 0                              # Sentinel master database index.
  #   # For single mode, put credentials in the Redis URL.
  # concurrency_ttl_secs: 300          # Redis backend only. Reclaims stale concurrency slots.

upstream:                             # Connection layer for outbound calls to providers. Values shown are the defaults.
  pool_idle_timeout_secs: 30          # Keep below the shortest idle timeout between the gateway and the provider.
  # connect_timeout_ms: 5000          # Budget for DNS, TCP, and TLS. 0 disables.
  # tcp_keepalive_secs: 60            # Idle time before the first keepalive probe. 0 disables.
  # tcp_keepalive_interval_secs: 30   # Interval between keepalive probes.
  # tcp_keepalive_retries: 5          # Unacknowledged probes before the connection is dropped.
  # pool_max_idle_per_host: 32        # Cap on idle connections per upstream host. Unset means unbounded.

# Optional deployment-wide override for AWS Bedrock guardrail traffic.
# bedrock_endpoint_url: "https://bedrock-runtime.us-east-1.amazonaws.com"

Changes to the startup configuration take effect after restarting the gateway.

Tune the Upstream Connection Layer

The upstream block controls how the gateway opens and reuses connections to providers. The defaults suit a gateway that reaches providers directly over the internet. Tune them when the gateway sits behind a load balancer, NAT gateway, corporate proxy, or service mesh.

pool_idle_timeout_secs is the setting to review first. The gateway reuses pooled connections, so this value must stay below the shortest idle timeout anywhere on the path to the provider. If an intermediate hop closes an idle connection sooner than the gateway expires it, the pool eventually hands out a connection the far end has already closed, and the request fails with a transport error against an otherwise healthy provider.

TCP keepalive keeps the connection visible to those same hops while a slow model produces its first token. A NAT or load-balancer idle timer can otherwise reap a connection that is legitimately waiting on a long-running request.

Every duration accepts 0 to switch that individual setting off.

Select a Configuration File

When running the binary directly, provide a config path with --config or AISIX_CONFIG.

aisix --config config.yaml

When running the official container image, mount the config file at /etc/aisix/config.yaml, or set AISIX_CONFIG_PATH to another path inside the container.

The following example mounts a production config file and asks the entrypoint to load it:

docker run \
  -v "$(pwd)/config.prod.yaml:/etc/aisix/config.prod.yaml:ro" \
  -e AISIX_CONFIG_PATH="/etc/aisix/config.prod.yaml" \
  ghcr.io/api7/aisix:latest

If AISIX_CONFIG_PATH is unset, the entrypoint uses /etc/aisix/config.yaml.

Loading Order

AISIX loads startup configuration in the following order:

1. Built-in default values.
2. File contents from the path selected by --config or AISIX_CONFIG.
3. Environment-variable overrides with the AISIX_ prefix.

Environment-variable overrides apply only to startup configuration fields. For override syntax and managed-gateway variables, see Environment Variables.