Configuration Files

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

Dynamic resources are not defined in startup configuration files. Models, caller API keys, provider keys, guardrails, cache policies, and observability exporters are stored in etcd and managed through the Admin API or AISIX Cloud 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 by the AISIX image when AISIX Cloud supplies control-plane 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.

Below are common configuration options in a self-hosted config.yaml:

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.
  dial_timeout_ms: 5000               # Timeout for establishing an etcd connection.
  request_timeout_ms: 5000            # Timeout for etcd requests.
  # tls:                              # TLS or mTLS settings for secure etcd connections.
  #   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 listener address (default). Always a separate listener; the admin API never serves /metrics.
    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 is managed by AISIX Cloud.
#   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.

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

Configurations in config.yaml are loaded at startup. Restart the gateway for changes to take effect.

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:dev

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.