Environment Variables

AISIX AI Gateway uses environment variables to select startup configuration files, override startup configuration fields, and provide deployment-specific values such as managed gateway certificate material.

Most runtime gateway resources are not configured through environment variables. Create models, caller API keys, provider keys, guardrails, cache policies, and observability exporters through the Admin API in self-hosted mode or through AISIX Cloud in managed mode.

Reserved Environment Variables

AISIX reserves the following environment variables:

Variable	Description
AISIX_CONFIG	Config file path used by the AISIX binary. Equivalent to passing --config.
AISIX_CONFIG_PATH	Config file path used by the official container entrypoint. Defaults to /etc/aisix/config.yaml.
RUST_LOG	Process logging directive. When unset, AISIX uses observability.log_level.
AISIX_DP_BUDGET_STALE_MAX_SECONDS	Maximum number of seconds a managed gateway can reuse a stale budget decision after the normal cache TTL. Defaults to 600.

To use these variables, assign values before starting AISIX.

Use AISIX_CONFIG when you run the binary directly:

export AISIX_CONFIG="/etc/aisix/config.yaml"
aisix

Use AISIX_CONFIG_PATH when you use the official container entrypoint:

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

The container entrypoint clears AISIX_CONFIG_PATH before starting the binary because it is an entrypoint variable, not a startup config field.

Startup Configuration Overrides

After AISIX loads the config file, it applies environment-variable overrides with the AISIX_ prefix. Use a single underscore after the prefix and double underscores between nested fields.

The following example overrides the proxy listener address:

export AISIX_PROXY__ADDR="0.0.0.0:3000"

The following example overrides the admin key list with a comma-separated value:

export AISIX_ADMIN__ADMIN_KEYS="admin-key-1,admin-key-2"

Common override variables include:

Variable	Overrides
AISIX_PROXY__ADDR	proxy.addr
AISIX_ADMIN__ADDR	admin.addr
AISIX_ADMIN__ADMIN_KEYS	admin.admin_keys
AISIX_ETCD__ENDPOINTS	etcd.endpoints
AISIX_ETCD__PREFIX	etcd.prefix
AISIX_OBSERVABILITY__LOG_LEVEL	observability.log_level
AISIX_CACHE__BACKEND	cache.backend
AISIX_BEDROCK_ENDPOINT_URL	Top-level bedrock_endpoint_url.

etcd.endpoints and admin.admin_keys accept comma-separated lists in environment variables.

For configuration file fields, see Configuration Files.

Managed Gateway Variables

Managed gateways use the same AISIX_ override mechanism for managed-mode startup settings.

Variable	Description
AISIX_MANAGED__ENABLED	Enables managed mode when set to true.
AISIX_MANAGED__CP_BASE_URL	Managed control-plane origin used for heartbeat, telemetry, certificate rotation, and budget checks.
AISIX_MANAGED__CP_ETCD_ENDPOINT	Managed etcd endpoint used by the gateway at startup.
AISIX_MANAGED__CP_CA_CERT_FILE	Optional CA bundle file used to trust AISIX Cloud control-plane and managed etcd TLS connections.
AISIX_MANAGED__CP_CERT_PEM	Inline client certificate PEM used for mTLS with AISIX Cloud.
AISIX_MANAGED__CP_KEY_PEM	Inline private key PEM paired with the client certificate.
AISIX_MANAGED__CP_CA_PEM	Inline CA certificate PEM used as the trust anchor.
AISIX_MANAGED__CP_CERT_FILE	File path for the client certificate PEM.
AISIX_MANAGED__CP_KEY_FILE	File path for the private key PEM.
AISIX_MANAGED__CP_CA_FILE	File path for the CA certificate PEM.
AISIX_MANAGED__MTLS_DIR	Directory where the gateway persists the materialized mTLS bundle.
AISIX_MANAGED__DP_ID_FILE	File where the gateway persists its managed gateway ID.
AISIX_MANAGED__SNAPSHOT_CACHE_PATH	File path for the on-disk snapshot cache used during control-plane outages.

Use either the inline PEM variables or the file-path variables for the certificate, key, and CA bundle. Do not mix inline and file variants for the same bundle.

For managed-mode setup, see Gateway Certificates and Managed Gateway.