Environment Variables

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

Most runtime gateway resources are not configured directly through environment variables. For an open-source AISIX gateway, declare models, caller API keys, provider keys, guardrails, cache policies, and observability exporters in a resources.yaml file. The file supports environment interpolation for values such as ${OPENAI_API_KEY}.

For an AISIX gateway connected to AISIX Cloud, the control plane supplies these resources.

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 gateway connected to AISIX Cloud 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/aisix:latest

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"

Common override variables include:

Variable	Overrides
AISIX_PROXY__ADDR	proxy.addr
AISIX_PROXY__THREAD_PER_CORE	proxy.thread_per_core
AISIX_PROXY__WORKERS	proxy.workers
AISIX_ETCD__ENDPOINTS	etcd.endpoints
AISIX_ETCD__PREFIX	etcd.prefix
AISIX_OBSERVABILITY__LOG_LEVEL	observability.log_level
AISIX_CACHE__REDIS__MODE	cache.redis.mode
AISIX_CACHE__REDIS__URL	cache.redis.url
AISIX_CACHE__REDIS__MASTER_NAME	cache.redis.master_name
AISIX_CACHE__REDIS__USERNAME	cache.redis.username
AISIX_CACHE__REDIS__PASSWORD	cache.redis.password
AISIX_CACHE__REDIS__DATABASE	cache.redis.database
AISIX_RATELIMIT__BACKEND	ratelimit.backend
AISIX_RATELIMIT__REDIS__MODE	ratelimit.redis.mode
AISIX_RATELIMIT__REDIS__URL	ratelimit.redis.url
AISIX_RATELIMIT__REDIS__MASTER_NAME	ratelimit.redis.master_name
AISIX_RATELIMIT__REDIS__USERNAME	ratelimit.redis.username
AISIX_RATELIMIT__REDIS__PASSWORD	ratelimit.redis.password
AISIX_RATELIMIT__REDIS__DATABASE	ratelimit.redis.database
AISIX_RATELIMIT__CONCURRENCY_TTL_SECS	ratelimit.concurrency_ttl_secs
AISIX_BEDROCK_ENDPOINT_URL	Top-level bedrock_endpoint_url.

etcd.endpoints accepts a comma-separated list in an environment variable.

For Redis Cluster and Sentinel node lists, configure cache.redis.nodes, cache.redis.sentinels, ratelimit.redis.nodes, or ratelimit.redis.sentinels in the startup configuration file.

For configuration file fields, see the Startup Configuration Reference.

AISIX Cloud Connection Variables

AISIX gateways use the same AISIX_ override mechanism for managed.* startup settings.

Variable	Description
AISIX_MANAGED__ENABLED	Connects the gateway to AISIX Cloud when set to true.
AISIX_MANAGED__CP_BASE_URL	AISIX Cloud control-plane origin used for heartbeat, telemetry, certificate rotation, and budget checks.
AISIX_MANAGED__CP_ETCD_ENDPOINT	Control-plane etcd endpoint used by the gateway at startup.
AISIX_MANAGED__CP_CA_CERT_FILE	Optional CA bundle file used to trust control-plane and etcd TLS connections.
AISIX_MANAGED__CP_CERT_PEM	Inline client certificate PEM used for mTLS with the AISIX Cloud control plane.
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 AISIX gateway ID.
AISIX_MANAGED__SNAPSHOT_CACHE_PATH	File path for the on-disk snapshot cache used during control-plane outages.
AISIX_MANAGED__HEARTBEAT_INTERVAL_SECS	AISIX gateway heartbeat interval in seconds. Defaults to 15; values are clamped between 5 and 300.

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 AISIX Cloud setup, see Connect an AISIX Gateway.