# Environment Variables Reference This reference is derived from `.env.example`, `docker-compose.yml`, `apps/gateway/context.ts`, and the route and helper modules that parse environment values. ## Quick reference table | Variable | Required | Default | Description | | ----------------------------------- | ----------- | -------------------------------------------- | -------------------------------------------------------------------- | | `OPENAI_API_KEY` | Conditional | none | Enables the first-party OpenAI provider | | `ANTHROPIC_API_KEY` | Conditional | none | Enables the first-party Anthropic provider | | `AZURE_OPENAI_API_KEY` | Conditional | none | Azure OpenAI credential | | `AZURE_OPENAI_ENDPOINT` | Conditional | none | Azure OpenAI resource endpoint | | `AZURE_OPENAI_API_VERSION` | Conditional | none | Azure OpenAI API version | | `AZURE_OPENAI_DEPLOYMENTS` | Conditional | none | Comma-separated Azure deployment names | | `GEMINI_API_KEY` | Conditional | none | Enables the Gemini provider | | `OPENROUTER_API_KEY` | Conditional | none | Enables the OpenRouter provider | | `GROQ_API_KEY` | Conditional | none | Enables the Groq provider | | `MISTRAL_API_KEY` | Conditional | none | Enables the Mistral provider | | `XAI_API_KEY` | Conditional | none | Enables the xAI provider | | `PERPLEXITY_API_KEY` | Conditional | none | Enables the Perplexity provider | | `CEREBRAS_API_KEY` | Conditional | none | Enables the Cerebras provider | | `NEBIUS_API_KEY` | Conditional | none | Enables the Nebius provider | | `PARASAIL_API_KEY` | Conditional | none | Enables the Parasail provider | | `HF_TOKEN` | Conditional | none | Enables Hugging Face access | | `COHERE_API_KEY` | Conditional | none | Enables the Cohere provider | | `ELEVENLABS_API_KEY` | Conditional | none | Enables ElevenLabs text-to-speech | | `OLLAMA_BASE_URL` | Conditional | none | Base URL for Ollama | | `OLLAMA_MODELS` | Conditional | none | Comma-separated Ollama models | | `AWS_REGION` | Conditional | `us-east-1` | Bedrock region | | `AWS_ACCESS_KEY_ID` | Conditional | none | Bedrock access key id | | `AWS_SECRET_ACCESS_KEY` | Conditional | none | Bedrock secret key | | `AWS_SESSION_TOKEN` | Conditional | none | Optional Bedrock session token | | `BEDROCK_MODELS` | Conditional | none | Comma-separated Bedrock models | | `VERTEX_PROJECT_ID` | Conditional | none | Vertex AI project id | | `VERTEX_LOCATION` | Conditional | `us-central1` | Vertex AI region | | `VERTEX_SERVICE_ACCOUNT_JSON` | Conditional | none | One-line Vertex service account JSON | | `VERTEX_MODELS` | Conditional | `gemini-2.5-pro` | Comma-separated Vertex models | | `OPENAI_COMPAT_BASE_URL` | Conditional | none | Enables a generic OpenAI-compatible provider | | `OPENAI_COMPAT_API_KEY` | Conditional | none | Credential for the generic OpenAI-compatible provider | | `OPENAI_COMPAT_DEFAULT_MODEL` | Conditional | none | Default model for the generic OpenAI-compatible provider | | `ANTHROPIC_COMPAT_BASE_URL` | Conditional | none | Enables a generic Anthropic-compatible provider | | `ANTHROPIC_COMPAT_API_KEY` | Conditional | none | Credential for the generic Anthropic-compatible provider | | `ANTHROPIC_COMPAT_DEFAULT_MODEL` | Conditional | none | Default model for the generic Anthropic-compatible provider | | `LMSTUDIO_BASE_URL` | Conditional | `http://localhost:1234/v1` | Base URL for LM Studio | | `LMSTUDIO_API_KEY` | Conditional | none | Optional LM Studio API key | | `LMSTUDIO_DEFAULT_MODEL` | Conditional | none | Default LM Studio model | | `PORT` | No | `8080` | Gateway listen port | | `LOG_LEVEL` | No | `info` | Gateway log level | | `FROSTY_DEFAULT_PROVIDER` | No | `openai` | Default provider for bare model ids | | `FROSTY_PG_URL` | Yes | none | Primary PostgreSQL connection string | | `FROSTY_PG_DIRECT_URL` | Conditional | none | Session-stable PostgreSQL URL for LISTEN when a pooler sits in front | | `FROSTY_PG_POOL_SIZE` | No | code default | Per-process PostgreSQL pool size | | `FROSTY_PG_TABLE` | No | `frosty_vectors` | pgvector table name | | `FROSTY_WORKERS` | No | single-process | Worker-process count | | `FROSTY_SHARED_RATE_LIMIT` | No | `auto` | Shared rate-limit authority mode | | `FROSTY_CONFIG_RECONCILE_MS` | No | `30000` | Config poll backstop interval in milliseconds | | `FROSTY_ADMIN_TOKEN` | No | none | Optional bearer token for `/api/*` | | `FROSTY_ALLOWED_HOSTS` | No | localhost, `127.0.0.1`, `::1` always allowed | Additional admin-origin allow-list hosts | | `FROSTY_CACHE` | No | off | Cache mode: unset, `exact`, or `semantic` | | `FROSTY_CACHE_TTL_MS` | No | code default | Cache TTL in milliseconds | | `FROSTY_CACHE_EMBED_MODEL` | No | `text-embedding-3-small` | Embedding model for semantic cache lookups | | `FROSTY_VECTOR_STORE` | No | none | Vector store implementation, currently `pgvector` when enabled | | `FROSTY_MCP_ALLOW_STDIO` | No | off | Enables stdio MCP transports when combined with runtime permission | | `FROSTY_MCP_HEALTH_INTERVAL_MS` | No | on-demand only | Periodic MCP health-check interval | | `FROSTY_LOG_STORE` | No | `pg` | Durable log-store mode, `pg` or `off` | | `FROSTY_LOG_STORE_MAX` | No | `5000` | Stored-log cap | | `FROSTY_LOG_EXCLUDE_PATHS` | No | `/healthz,/metrics,/favicon.ico` | Paths excluded from the dashboard log trail | | `FROSTY_EUR_RATE` | No | `0.92` | Operator display conversion rate from USD to EUR | | `OTEL_EXPORTER_OTLP_ENDPOINT` | No | off | OTLP HTTP endpoint for traces | | `OTEL_FLUSH_INTERVAL_MS` | No | `5000` | OTEL batch flush interval | | `FROSTY_OTEL_MODEL_CARDINALITY_CAP` | No | `11` | Distinct model-label cap for span-derived metrics | | `FROSTY_PRICING_SYNC` | No | off | Enables periodic LiteLLM pricing sync | | `FROSTY_PRICING_SYNC_INTERVAL_MS` | No | `86400000` | Pricing sync interval in milliseconds | | `FROSTY_PRICING_URL` | No | LiteLLM upstream JSON URL | Source for pricing sync | | `FROSTY_ENCRYPTION_KEY` | No | off | Opt-in config encryption key | | `FROSTY_ENCRYPTION_KEY_OLD` | No | none | Previous encryption key used for rotation | | `FROSTY_JSON_REPAIR` | No | off | Enables the JSON-repair plugin | | `FROSTY_MOCKER` | No | off | Enables the mock-response plugin | | `FROSTY_MOCKER_CONFIG` | Conditional | none | Inline JSON or file path for mocker rules | | `FROSTY_HTTP_TIMEOUT_MS` | No | `120000` | Default provider HTTP timeout in milliseconds | | `FROSTY_NO_PROXY` | No | none | Comma-separated proxy bypass rules | | `FROSTY_LOG_CONTENT` | No | off | Enables request and response content capture in stored logs | | `FROSTY_CODE_MODE` | No | `off` | Enables Code Mode surfaces and capability probing | | `FROSTY_CODE_MODE_VFS` | No | `on` | Enables Code Mode VFS metadata surface | ## Categorized reference ### Provider credentials and provider catalogs Variables: - `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY` - `GROQ_API_KEY`, `MISTRAL_API_KEY`, `XAI_API_KEY`, `PERPLEXITY_API_KEY`, `CEREBRAS_API_KEY`, `NEBIUS_API_KEY`, `PARASAIL_API_KEY`, `HF_TOKEN`, `COHERE_API_KEY`, `ELEVENLABS_API_KEY` - `OLLAMA_BASE_URL`, `OLLAMA_MODELS` Notes: - All are optional individually and only required when that provider is intended to boot automatically from env. - Model lists use comma-separated values where present. - Secrets in this category must never be committed to version control. - Example: `OPENAI_API_KEY=sk-...`, `OLLAMA_BASE_URL=http://localhost:11434`, `OLLAMA_MODELS=llama3.1,codellama`. ### Azure OpenAI, Bedrock, and Vertex AI Variables: - Azure: `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_API_VERSION`, `AZURE_OPENAI_DEPLOYMENTS` - Bedrock: `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `BEDROCK_MODELS` - Vertex: `VERTEX_PROJECT_ID`, `VERTEX_LOCATION`, `VERTEX_SERVICE_ACCOUNT_JSON`, `VERTEX_MODELS` Notes: - These groups are conditionally required as complete sets for their respective providers. - `VERTEX_SERVICE_ACCOUNT_JSON` is expected as a single-line JSON string. - `AZURE_OPENAI_DEPLOYMENTS`, `BEDROCK_MODELS`, and `VERTEX_MODELS` are comma-separated lists. - All cloud credentials in this category should be treated as secrets. ### Generic compatible endpoints Variables: - `OPENAI_COMPAT_BASE_URL`, `OPENAI_COMPAT_API_KEY`, `OPENAI_COMPAT_DEFAULT_MODEL` - `ANTHROPIC_COMPAT_BASE_URL`, `ANTHROPIC_COMPAT_API_KEY`, `ANTHROPIC_COMPAT_DEFAULT_MODEL` - `LMSTUDIO_BASE_URL`, `LMSTUDIO_API_KEY`, `LMSTUDIO_DEFAULT_MODEL` Notes: - Each compatible endpoint stays off until its `*_BASE_URL` is set. - `LMSTUDIO_BASE_URL` defaults to `http://localhost:1234/v1`. - These variables let Frosty wrap third-party or local compatible servers as provider accounts. ### Core gateway and PostgreSQL Variables: - `PORT`, `LOG_LEVEL`, `FROSTY_DEFAULT_PROVIDER` - `FROSTY_PG_URL`, `FROSTY_PG_DIRECT_URL`, `FROSTY_PG_POOL_SIZE`, `FROSTY_PG_TABLE` Notes: - `FROSTY_PG_URL` is effectively mandatory on the production path because PostgreSQL is a hard dependency. - `FROSTY_PG_DIRECT_URL` matters when PgBouncer is used, because LISTEN needs a session-stable connection. - `FROSTY_PG_TABLE` controls the pgvector table name used by the semantic cache. - Example: `FROSTY_PG_URL=postgres://frosty:frosty@localhost:5432/frosty`. ### Worker topology and shared governance Variables: - `FROSTY_WORKERS`, `FROSTY_SHARED_RATE_LIMIT`, `FROSTY_CONFIG_RECONCILE_MS` Notes: - `FROSTY_WORKERS` values greater than 1 trigger the multi-process supervisor on supported operating systems. - `FROSTY_SHARED_RATE_LIMIT` accepts `auto`, `on`, or `off`. - `FROSTY_CONFIG_RECONCILE_MS` bounds staleness when LISTEN/NOTIFY is missed. ### Admin protection and origin control Variables: - `FROSTY_ADMIN_TOKEN`, `FROSTY_ALLOWED_HOSTS` Notes: - Leaving `FROSTY_ADMIN_TOKEN` unset results in local-admin mode. - `FROSTY_ALLOWED_HOSTS` is a comma-separated host allow-list for the admin origin guard. - Example: `FROSTY_ALLOWED_HOSTS=gw.example.com,admin.internal.example.com`. ### Cache and vector store Variables: - `FROSTY_CACHE`, `FROSTY_CACHE_TTL_MS`, `FROSTY_CACHE_EMBED_MODEL`, `FROSTY_VECTOR_STORE` Notes: - `FROSTY_CACHE` is unset for off, `exact` for exact-match caching, and `semantic` for embedding-assisted lookup. - `FROSTY_VECTOR_STORE` is only relevant when semantic cache is on. - `FROSTY_CACHE_EMBED_MODEL` must match a model id the configured provider can serve. ### MCP and Code Mode Variables: - `FROSTY_MCP_ALLOW_STDIO`, `FROSTY_MCP_HEALTH_INTERVAL_MS` - `FROSTY_CODE_MODE`, `FROSTY_CODE_MODE_VFS` Notes: - `FROSTY_MCP_ALLOW_STDIO` only takes effect when the runtime also has `--allow-run` for the Deno binary. - `FROSTY_CODE_MODE` defaults to `off` and remains additionally gated by the capability probe. - `FROSTY_CODE_MODE_VFS` controls the VFS metadata surface and defaults to `on` in the example env. ### Logging, analytics display, and observability Variables: - `FROSTY_LOG_STORE`, `FROSTY_LOG_STORE_MAX`, `FROSTY_LOG_EXCLUDE_PATHS`, `FROSTY_EUR_RATE`, `FROSTY_LOG_CONTENT` - `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_FLUSH_INTERVAL_MS`, `FROSTY_OTEL_MODEL_CARDINALITY_CAP` Notes: - `FROSTY_LOG_STORE=pg` keeps the durable PostgreSQL trail on; `off` disables it. - `FROSTY_LOG_EXCLUDE_PATHS` accepts exact paths and `/prefix/*` patterns. - `FROSTY_LOG_CONTENT` is privacy-sensitive and off by default. - `OTEL_EXPORTER_OTLP_ENDPOINT` turns trace export on when set. ### Pricing sync, encryption, plugins, and HTTP client tuning Variables: - `FROSTY_PRICING_SYNC`, `FROSTY_PRICING_SYNC_INTERVAL_MS`, `FROSTY_PRICING_URL` - `FROSTY_ENCRYPTION_KEY`, `FROSTY_ENCRYPTION_KEY_OLD` - `FROSTY_JSON_REPAIR`, `FROSTY_MOCKER`, `FROSTY_MOCKER_CONFIG` - `FROSTY_HTTP_TIMEOUT_MS`, `FROSTY_NO_PROXY` Notes: - `FROSTY_PRICING_SYNC` is opt-in and off by default. - `FROSTY_ENCRYPTION_KEY` enables AES-256-GCM encryption-at-rest behavior and becomes effectively mandatory for subsequent boots once encrypted data exists. - `FROSTY_MOCKER_CONFIG` accepts inline JSON or a file path. - `FROSTY_NO_PROXY` is a comma-separated bypass list. ## Example configurations ### Minimal development setup ```dotenv OPENAI_API_KEY=sk-your-key PORT=8080 FROSTY_DEFAULT_PROVIDER=openai FROSTY_PG_URL=postgres://frosty:frosty@localhost:5432/frosty FROSTY_LOG_STORE=pg ``` ### Docker Compose development ```dotenv PORT=8080 OPENAI_API_KEY=sk-your-key FROSTY_DEFAULT_PROVIDER=openai FROSTY_PG_URL=postgres://frosty:frosty@postgres:5432/frosty FROSTY_LOG_STORE=pg OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4318 ``` ### Production-oriented example ```dotenv PORT=8080 OPENAI_API_KEY=sk-your-key FROSTY_DEFAULT_PROVIDER=openai FROSTY_PG_URL=postgres://user:pass@db.internal:5432/frosty FROSTY_PG_DIRECT_URL=postgres://user:pass@db.internal:5432/frosty FROSTY_ADMIN_TOKEN=replace-me FROSTY_ALLOWED_HOSTS=gw.example.com FROSTY_LOG_STORE=pg FROSTY_SHARED_RATE_LIMIT=on FROSTY_ENCRYPTION_KEY=base64-encoded-32-byte-key ``` ## Security best practices - Never commit provider keys, cloud credentials, admin tokens, or encryption keys. - Prefer environment injection from a secret store or deployment platform rather than a committed `.env` file. - Rotate `FROSTY_ADMIN_TOKEN`, provider API keys, and `FROSTY_ENCRYPTION_KEY` according to your operational policy. - Treat `FROSTY_LOG_CONTENT` as a privacy-sensitive switch and leave it off unless content capture is explicitly required. - Do not embed credentials in proxy URLs; the provider-config schema separates proxy credentials from proxy URL fields for that reason. ## Troubleshooting - If the gateway refuses to boot, verify `FROSTY_PG_URL` connectivity first. PostgreSQL is a hard dependency on the production path. - If config changes do not appear across replicas, check `FROSTY_PG_DIRECT_URL` and `FROSTY_CONFIG_RECONCILE_MS`. - If semantic cache lookups never hit, verify `FROSTY_CACHE=semantic`, `FROSTY_VECTOR_STORE=pgvector`, and `FROSTY_CACHE_EMBED_MODEL` against `GET /v1/models`. - If admin writes are rejected cross-origin, check `FROSTY_ALLOWED_HOSTS` and confirm the request is targeting `/api/*` from an allowed host. - If trace export is missing, verify `OTEL_EXPORTER_OTLP_ENDPOINT` and the observability profile services. - If encrypted config becomes unreadable, confirm `FROSTY_ENCRYPTION_KEY` is still present and, during rotation, that `FROSTY_ENCRYPTION_KEY_OLD` matches the previous key.