Configuration Files

AISIX AI Gateway uses startup configuration files to define process-level settings such as listeners, etcd connectivity, TLS, observability, cache backend, 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
• config.example.yaml
• config.managed.yaml

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.
    - "admin-local-only-change-me"
  # 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"          # Optional dedicated metrics 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 is managed by AISIX Cloud.
#   enabled: true

cache:
  backend: "memory"                   # Default cache backend. Use redis only with a redis block.
  # redis:                            # Redis connection used by cache policies that select Redis.
  #   url: "redis://127.0.0.1:6379"
  #   mode: "single"

# 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/ai-gateway: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.