Browse docs
--- title: "Configuration" description: "How to configure Aurora using environment variables, .env files, and YAML." icon: "sliders-horizontal" --- ## Good defaults Aurora uses a good defaults philosophy. This means that the default settings should be enough to use it. ## How to override the default settings? We use a three-layer configuration pipeline. Every setting has a sensible default, so you can start the server with zero configuration. ``mermaid flowchart RL C[Code Defaults] -->|"fallback"| B[config.yaml] B -->|"fallback"| A[Environment Variables] style A stroke:#22c55e,stroke-width:3px style B stroke:#f59e0b,stroke-width:2px style C stroke:#6b7280,stroke-width:1px ` <Tip> As Aurora works out of the box with no configuration files, you can try it in a minute. Start here: Quick Start </Tip> Aurora automatically discovers providers from well-known environment variables. ## Configuration Methods ### 1. Environment Variables The most common way to configure Aurora. Set any of the variables below to override defaults. #### Server | Variable | Description | Default | | -------------------- | ----------------------------------------------------- | ---------------------- | | PORT | HTTP server port | 8080 | | BASE_PATH | Mount path prefix, for example /g | / | | AURORA_MASTER_KEY | Authentication key for securing the gateway | _(empty, unsafe mode)_ | | BODY_SIZE_LIMIT | Max request body size (e.g., 10M, 1024K, 500KB) | 10MB | #### Logging Runtime logger output. For the persisted API audit trail (request/response bodies, headers), see Audit Logging below. | Variable | Description | Default | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------- | | LOG_FORMAT | text for colorized human output, json for structured logs. Unset auto-detects: text on a TTY, JSON otherwise. Force json in production / CloudWatch / Datadog / GCP setups. | _(auto-detect)_ | | LOG_LEVEL | Minimum log level: debug, info, warn, error. Aliases dbg, inf, warning, err are also accepted. | info | #### Cache | Variable | Description | Default | | ------------------- | --------------------------------- | ---------------- | | AURORA_CACHE_DIR | Directory for local cache files | .cache | | REDIS_URL | Redis connection URL | _(empty)_ | | REDIS_KEY_MODELS | Redis key for model cache | aurora:models | | REDIS_KEY_RESPONSES | Redis key for response cache | aurora:response: | | REDIS_TTL_MODELS | TTL in seconds for model cache | 86400 (24h) | | REDIS_TTL_RESPONSES | TTL in seconds for response cache | 3600 (1h) | <Note> Redis is configured only when REDIS_URL is set. The key and TTL defaults above apply after Redis is enabled. With no Redis URL, the model cache defaults to local file-based storage instead. </Note> <Tip> See Cache for exact-cache behavior, response headers, analytics endpoints, and the note that user_path alone does not partition the exact cache. </Tip> #### Provider Prompt Caching | Variable | Description | Default | | -------- | ----------- | ------- | | PROMPT_CACHE_MODE | Caching mode: auto, manual, or off | auto | | PROMPT_CACHE_SYSTEM | Mark system prompts for caching (auto mode) | true | | PROMPT_CACHE_FIRST_MESSAGE | Mark first user message for caching (auto mode) | true | | PROMPT_CACHE_TOOLS | Mark tool definitions for caching (auto mode) | false | | PROMPT_CACHE_MIN_TOKENS | Minimum cumulative tokens before a cache breakpoint | 1024 | See Provider Prompt Caching for provider-specific behavior and how this differs from gateway-level response caching. #### Storage Storage is shared by audit logging, usage tracking, and future features like IAM. | Variable | Description | Default | | -------------------- | --------------------------------------------- | ----------------- | | STORAGE_TYPE | Backend: sqlite, postgresql, or mongodb | sqlite | | SQLITE_PATH | SQLite database file path | data/aurora.db | | POSTGRES_URL | PostgreSQL connection string | _(empty)_ | | POSTGRES_MAX_CONNS | PostgreSQL connection pool size | 10 | | MONGODB_URL | MongoDB connection string | _(empty)_ | | MONGODB_DATABASE | MongoDB database name | aurora | #### Audit Logging | Variable | Description | Default | | --------------------------------- | ------------------------------------------ | ------- | | LOGGING_ENABLED | Enable audit logging | false | | LOGGING_LOG_BODIES | Log request/response bodies | true | | LOGGING_LOG_HEADERS | Log headers (sensitive ones auto-redacted) | true | | LOGGING_ONLY_MODEL_INTERACTIONS | Only log AI model endpoints | true | | LOGGING_BUFFER_SIZE | In-memory buffer before flush | 1000 | | LOGGING_FLUSH_INTERVAL | Flush interval in seconds | 5 | | LOGGING_RETENTION_DAYS | Auto-delete after N days (0 = forever) | 30 | <Warning> When LOGGING_LOG_BODIES is enabled, request and response bodies are stored in full. These may contain sensitive data such as PII or API keys embedded in prompts. </Warning> #### Token Usage Tracking | Variable | Description | Default | | ------------------------------ | ---------------------------------------------- | ------- | | USAGE_ENABLED | Enable token usage tracking | true | | USAGE_PRICING_RECALCULATION_ENABLED | Enable the admin usage pricing recalculation action when supported | true | | ENFORCE_RETURNING_USAGE_DATA | Auto-add include_usage to streaming requests | true | | USAGE_BUFFER_SIZE | In-memory buffer before flush | 1000 | | USAGE_FLUSH_INTERVAL | Flush interval in seconds | 5 | | USAGE_RETENTION_DAYS | Auto-delete after N days (0 = forever) | 90 | #### Budgets Budgets use tracked usage cost records. If usage tracking is disabled, Aurora starts with budget management disabled and logs a warning. <Note> Budget admin endpoints and dashboard panels require the Enterprise advancedBudgets capability. Keep BUDGETS_ENABLED=false in OSS profiles unless you are testing capability gates. </Note> | Variable | Description | Default | | ------------------- | ------------------------------------------------------- | ------- | | BUDGETS_ENABLED | Enable budget management and workflow budget checks when usage tracking is enabled and the edition has advancedBudgets | false | | SET_BUDGET_<PATH> | Seed budget limits for a user path, such as daily=10 | _(empty)_ | SET_BUDGET_<PATH> supports the standard periods hourly, daily, weekly, and monthly. The <PATH> suffix is lowercased; use double underscores (__) between path segments, while single underscores stay inside a segment. For example, SET_BUDGET_TEAM__ALPHA__SERVICE="daily=10" configures /team/alpha/service, and SET_BUDGET_TEAM_ALPHA="daily=10" configures /team_alpha. This differs from provider <SUFFIX> variables below, which convert underscores to hyphens in provider names. SET_BUDGET_="monthly=500" means a literal environment variable named SET_BUDGET_, which configures the root path /. POSIX permits that name, but some shells and orchestrators, including some Kubernetes validators, may reject it. Use YAML or the dashboard when your environment cannot set it. Migration note: budget management depends on usage tracking. If USAGE_ENABLED=false, Aurora starts with budgets disabled and logs a warning, even when BUDGETS_ENABLED=true. Set both USAGE_ENABLED=true and BUDGETS_ENABLED=true in an Enterprise profile to enforce budgets. See Budgets for YAML examples, periods, matching, and workflow enforcement. #### Token Saver Token Saver appends output-style instructions (terse "caveman" mode) to selected chat completion requests. This reduces token consumption from verbose model responses. | Variable | Description | Default | |---|---|---| | TOKEN_SAVER_ENABLED | Enable Token Saver | false | | TOKEN_SAVER_ENDPOINTS | Comma-separated endpoints to apply to | chat_completions | | TOKEN_SAVER_APPLY_STREAMING | Apply instructions to streaming requests | true | | TOKEN_SAVER_ON_ERROR | allow to pass through on failure, block to reject | allow | | TOKEN_SAVER_EMIT_HEADERS | Emit X-Aurora-Token-Saver-* response headers | true | Output profile: | Variable | Description | Default | |---|---|---| | TOKEN_SAVER_OUTPUT_ENABLED | Enable output instruction injection | false | | TOKEN_SAVER_OUTPUT_PROFILE | Output profile — currently only concise | concise | | TOKEN_SAVER_OUTPUT_LEVEL | Verbosity: lite, full, ultra, wenyan | full | Model/provider scoping: | Variable | Description | Default | |---|---|---| | TOKEN_SAVER_MODELS_INCLUDE | Comma-separated model names to apply to | _(all)_ | | TOKEN_SAVER_MODELS_EXCLUDE | Comma-separated model names to skip | _(none)_ | | TOKEN_SAVER_PROVIDERS_INCLUDE | Comma-separated provider names to apply to | _(all)_ | | TOKEN_SAVER_PROVIDERS_EXCLUDE | Comma-separated provider names to skip | _(none)_ | Audit: | Variable | Description | Default | |---|---|---| | TOKEN_SAVER_AUDIT_ENABLED | Emit audit events when Token Saver fires | true | `yaml token_saver: enabled: true endpoints: ["chat_completions"] apply_streaming: true on_error: allow emit_headers: true output: enabled: true profile: concise level: full models: exclude: ["o1-pro"] providers: include: ["openai", "anthropic"] audit: enabled: true ` #### CLI Tools CLI Tools allow executing configured shell commands through the admin API. | Variable | Description | Default | |---|---|---| | CLI_TOOLS_ENABLED | Enable CLI tools API | true | | CLI_TOOLS_APPLY_ENABLED | Allow destructive apply actions | false | `yaml cli_tools: enabled: true apply_enabled: false ` #### Metrics <Note> Prometheus support is experimental. See the Prometheus Metrics guide for details. </Note> | Variable | Description | Default | | ------------------ | ---------------------------------------- | ---------- | | METRICS_ENABLED | Enable Prometheus metrics (experimental) | false | | METRICS_ENDPOINT | HTTP path for metrics | /metrics | #### Admin | Variable | Description | Default | | ------------------------- | ----------------------------- | ------- | | ADMIN_ENDPOINTS_ENABLED | Enable the admin REST API | true | | ADMIN_UI_ENABLED | Enable the admin dashboard UI | true | #### HTTP Client These control timeouts for upstream API requests to LLM providers. | Variable | Description | Default | | ------------------------------ | -------------------------------------------- | -------------- | | HTTP_TIMEOUT | Overall request timeout in seconds | 600 (10 min) | | HTTP_RESPONSE_HEADER_TIMEOUT | Time to wait for response headers in seconds | 600 (10 min) | ##### HTTP Proxy Configure outbound proxy for upstream API requests. Empty values use the environment's proxy settings (HTTP_PROXY, HTTPS_PROXY, NO_PROXY). | Variable | Description | Default | | ---------------- | ------------------------------------------------------ | --------- | | HTTP_PROXY | HTTP proxy URL for outbound requests | _(empty)_ | | HTTPS_PROXY | HTTPS proxy URL for outbound requests | _(empty)_ | | NO_PROXY | Comma-separated hosts to exclude from proxying | _(empty)_ | In YAML: `yaml http: proxy: http_proxy: "http://proxy.internal:8080" https_proxy: "http://proxy.internal:8080" no_proxy: "localhost,127.0.0.1,.internal" proxy_auth_enabled: false ca_cert_pem: "" ` #### Provider API Keys Set these to automatically register providers. No YAML configuration required. | Variable | Provider | | -------------------- | -------------------------------------------------- | | OPENAI_API_KEY | OpenAI | | ANTHROPIC_API_KEY | Anthropic | | GEMINI_API_KEY | Google Gemini | | DEEPSEEK_API_KEY | DeepSeek | | OPENROUTER_API_KEY | OpenRouter | | ZAI_API_KEY | Z.ai | | XAI_API_KEY | xAI (Grok) | | GROQ_API_KEY | Groq | | AZURE_API_KEY | Azure OpenAI (AZURE_BASE_URL also required) | | ORACLE_API_KEY | Oracle (ORACLE_BASE_URL also required) | | OLLAMA_BASE_URL | Ollama (no API key needed) | | VLLM_BASE_URL | vLLM (no API key needed unless upstream requires) | Most providers can use a custom base URL via <PROVIDER>_BASE_URL (for example OPENAI_BASE_URL). DeepSeek defaults to https://api.deepseek.com; set DEEPSEEK_BASE_URL only for a compatible proxy or alternate DeepSeek endpoint. OpenRouter defaults to https://openrouter.ai/api/v1 and can be overridden with OPENROUTER_BASE_URL. Z.ai defaults to https://api.z.ai/api/paas/v4; set ZAI_BASE_URL=https://api.z.ai/api/coding/paas/v4 for the GLM Coding Plan endpoint. vLLM defaults to http://localhost:8000/v1 when VLLM_API_KEY is set, but keyless deployments should set VLLM_BASE_URL explicitly to register the provider. Azure uses AZURE_BASE_URL for its deployment base URL and accepts an optional AZURE_API_VERSION override; otherwise it defaults to 2024-10-21. Oracle requires ORACLE_BASE_URL because its OpenAI-compatible endpoint is region-specific. Every provider type also accepts a comma-separated configured model list via <PROVIDER>_MODELS, for example OPENROUTER_MODELS, ORACLE_MODELS, AZURE_MODELS, or VLLM_MODELS. By default, CONFIGURED_PROVIDER_MODELS_MODE=fallback uses configured lists only when upstream /models fails, returns nil, or returns an empty list. Set CONFIGURED_PROVIDER_MODELS_MODE=allowlist to expose only configured models for providers that define a list and skip their upstream /models calls. YAML providers.<name>.models provides the same model-list input for named provider blocks. For OpenRouter, Aurora also sends default attribution headers unless the request already sets them. Override those defaults with OPENROUTER_SITE_URL and OPENROUTER_APP_NAME. ### 2. .env File Aurora automatically loads a .env file from the working directory at startup. This is convenient for local development. `bash # .env PORT=3000 BASE_PATH=/g OPENAI_API_KEY=<your OpenAI API key> ANTHROPIC_API_KEY=<your Anthropic API key> ` Copy .env.template to .env and uncomment the values you need: `bash cp .env.template .env ` <Note> Real environment variables always override values from the .env file. The .env file is only loaded if it exists — missing it is not an error. </Note> ### 3. Configuration File (YAML) For more complex setups, you can use an optional YAML configuration file. Aurora looks for it in two locations (in order): 1. config/config.yaml 2. config.yaml If you are deciding whether you need YAML at all, see config.yaml. To get started, copy the example: `bash cp config/config.example.yaml config/config.yaml ` Then uncomment and edit the settings you want to change: `yaml server: port: "3000" base_path: "/g" master_key: "${AURORA_MASTER_KEY}" cache: model: redis: url: "redis://my-redis:6379" budgets: enabled: true user_paths: - path: "/team/alpha" limits: - period: "daily" amount: 10.00 - period: "weekly" amount: 50.00 providers: openai: type: openai api_key: "${OPENAI_API_KEY}" anthropic: type: anthropic api_key: "${ANTHROPIC_API_KEY}" # Custom OpenAI-compatible provider my-custom-llm: type: openai base_url: "${CUSTOM_OPENAI_COMPATIBLE_BASE_URL}" api_key: "${CUSTOM_OPENAI_COMPATIBLE_API_KEY}" ` The YAML file supports environment variable expansion using ${VAR} and ${VAR:-default} syntax: `yaml server: port: "${PORT:-8080}" providers: openai: type: openai api_key: "${OPENAI_API_KEY}" ` <Tip> The YAML file is entirely optional. Any setting you can put in YAML can also be set via environment variables. Use YAML when you need per-provider resilience overrides, generated provider names are not enough, or you prefer a structured config file. </Tip> ## Provider Configuration ### Auto-Discovery from Environment Variables The simplest way to add providers. Aurora checks for well-known API key environment variables and automatically registers providers: `bash export OPENAI_API_KEY="$OPENAI_API_KEY" # Registers "openai" provider export ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" # Registers "anthropic" provider export GEMINI_API_KEY="$GEMINI_API_KEY" # Registers "gemini" provider export DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" # Registers "deepseek" provider export XAI_API_KEY="$XAI_API_KEY" # Registers "xai" provider export GROQ_API_KEY="$GROQ_API_KEY" # Registers "groq" provider export OPENROUTER_API_KEY="$OPENROUTER_API_KEY" # Registers "openrouter" provider export ZAI_API_KEY="$ZAI_API_KEY" # Registers "zai" provider # Optional: export ZAI_BASE_URL="https://api.z.ai/api/coding/paas/v4" export AZURE_API_KEY="..." # Registers "azure" provider when paired with AZURE_BASE_URL export AZURE_BASE_URL="https://your-resource.openai.azure.com/openai/deployments/your-deployment" export ORACLE_API_KEY="..." # Registers "oracle" provider when paired with ORACLE_BASE_URL export ORACLE_BASE_URL="https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1" export ORACLE_MODELS="openai.gpt-oss-120b,xai.grok-3" # Optional configured model list export OPENROUTER_MODELS="openai/gpt-oss-120b,anthropic/claude-sonnet-4" export CONFIGURED_PROVIDER_MODELS_MODE="fallback" # fallback or allowlist export OLLAMA_BASE_URL="http://localhost:11434/v1" # Registers "ollama" provider export VLLM_BASE_URL="http://localhost:8000/v1" # Registers keyless "vllm" provider # Optional: export VLLM_API_KEY="token-abc123" ` Use suffixed variables to register more than one instance of the same provider type without YAML. Aurora normalizes the suffix to lowercase and converts underscores to hyphens in the configured provider name: `bash export OPENAI_EAST_API_KEY="$OPENAI_EAST_API_KEY" # Registers "openai-east", type "openai" export OPENAI_EAST_BASE_URL="$OPENAI_EAST_BASE_URL" export OPENAI_WEST_API_KEY="$OPENAI_WEST_API_KEY" # Registers "openai-west", type "openai" export OPENAI_WEST_BASE_URL="$OPENAI_WEST_BASE_URL" ` The same pattern works for every registered provider type: <PROVIDER>_<SUFFIX>_API_KEY, <PROVIDER>_<SUFFIX>_BASE_URL, and <PROVIDER>_<SUFFIX>_MODELS. Azure also supports <PROVIDER>_<SUFFIX>_API_VERSION. Azure and Oracle still require their suffixed BASE_URL values because their endpoints are deployment- or region-specific. ### YAML Provider Blocks For more control (custom names, per-provider resilience, or larger structured settings), use the YAML file: `yaml models: # fallback is the default. Use allowlist when configured provider model lists # should hide upstream models and skip upstream /models calls. configured_provider_models_mode: fallback providers: # Override OpenAI base URL openai: type: openai api_key: "${OPENAI_API_KEY}" base_url: "${OPENAI_BASE_URL}" # Add a second OpenAI-compatible endpoint azure: type: azure base_url: "https://my-resource.openai.azure.com/openai/deployments/gpt-4" api_key: "..." api_version: "2024-10-21" # Add Oracle's OpenAI-compatible endpoint oracle: type: oracle base_url: "https://inference.generativeai.us-chicago-1.oci.oraclecloud.com/20231130/actions/v1" api_key: "..." models: - openai.gpt-oss-120b - xai.grok-3 # Add DeepSeek. Aurora translates /v1/responses to DeepSeek chat completions. deepseek: type: deepseek base_url: "https://api.deepseek.com" api_key: "..." # Add a vLLM OpenAI-compatible server vllm: type: vllm base_url: "http://localhost:8000/v1" # api_key is optional; set it only when vllm serve uses --api-key. # api_key: "token-abc123" # Configure a model list for fallback or allowlist mode gemini: type: gemini api_key: "..." models: - gemini-2.0-flash - gemini-1.5-pro ` <Note> models: works for every provider block. In fallback mode it is a safety net when upstream /models is unavailable or empty. In allowlist mode it becomes the exposed inventory for that provider and skips upstream /models. For Oracle, see the Oracle guide for the required OCI policy and a tested configuration. </Note> ### Ollama (Local Models) Ollama does not require an API key. Set the base URL to enable it: `bash export OLLAMA_BASE_URL="http://localhost:11434/v1" ` Or in YAML: `yaml providers: ollama: type: ollama base_url: "http://localhost:11434/v1" ` ### vLLM vLLM uses its OpenAI-compatible /v1 API. In Docker, set VLLM_BASE_URL to register a keyless vLLM server: `bash docker run --rm -p 8080:8080 \ -e AURORA_MASTER_KEY="change-me" \ -e VLLM_BASE_URL="http://host.docker.internal:8000/v1" \ aurorallm/aurora ` If the upstream server was started with vllm serve ... --api-key token-abc123, also set: `bash docker run --rm -p 8080:8080 \ -e AURORA_MASTER_KEY="change-me" \ -e VLLM_BASE_URL="http://host.docker.internal:8000/v1" \ -e VLLM_API_KEY="token-abc123" \ aurorallm/aurora ` You can also register more than one vLLM instance without YAML: `bash docker run --rm -p 8080:8080 \ -e AURORA_MASTER_KEY="change-me" \ -e VLLM_BASE_URL="http://host.docker.internal:8000/v1" \ -e VLLM_TEST_BASE_URL="http://host.docker.internal:8000/v1" \ aurorallm/aurora ` This registers providers vllm and vllm-test. Use YAML only when the generated provider names are not enough or you need a larger structured block. ## Provider Behavior Notes ### Anthropic max_tokens default Anthropic requires max_tokens on every /v1/messages request. If a client omits it, Aurora injects a fallback so the request still succeeds. OpenAI and Gemini treat the field as optional and Aurora does not inject a default for them. | Variable | Description | Default | | ------------------------------ | ------------------------------------------------- | ------- | | ANTHROPIC_DEFAULT_MAX_TOKENS | Value injected when the caller omits max_tokens | 4096 | Raise this for newer models that routinely produce longer outputs (Sonnet 4.6, Opus 4.7). Setting max_tokens explicitly on a request always wins over the env-driven default. Invalid or non-positive values fall back to 4096`.