environment-variables.md

title	Environment Variables
description	All environment variables supported by Forge.
order	3

Environment Variables

Variable	Description
FORGE_MODEL_PROVIDER	Override LLM provider
FORGE_MODEL_FALLBACKS	Fallback chain (e.g., "anthropic:claude-sonnet-4,gemini")
FORGE_MEMORY_PERSISTENCE	Set false to disable session persistence
FORGE_MEMORY_LONG_TERM	Set true to enable long-term memory
FORGE_COMPRESSION	Set true/false to override compression.enabled (reversible context compression); the --compression flag overrides both
FORGE_EMBEDDING_PROVIDER	Override embedding provider
OPENAI_API_KEY	OpenAI API key
OPENAI_ORG_ID	OpenAI Organization ID (enterprise); overrides organization_id in YAML
ANTHROPIC_API_KEY	Anthropic API key
GEMINI_API_KEY	Google Gemini API key
TAVILY_API_KEY	Tavily web search API key
PERPLEXITY_API_KEY	Perplexity web search API key
WEB_SEARCH_PROVIDER	Force web search provider (tavily or perplexity)
OPENAI_BASE_URL	Override OpenAI base URL
ANTHROPIC_BASE_URL	Override Anthropic base URL
OLLAMA_BASE_URL	Override Ollama base URL (default: http://localhost:11434)
FORGE_CORS_ORIGINS	Comma-separated CORS allowed origins for A2A server
FORGE_AUTH_URL	External auth provider URL for token validation
FORGE_AUTH_ORG_ID	Organization ID sent to external auth provider
FORGE_GUARDRAILS_DB	MongoDB URI for DB-backed guardrails config + audit
FORGE_AGENT_ID	Agent identifier for DB guardrails (falls back to agent_id in YAML)
FORGE_ORG_ID	Organization identifier for DB guardrails
FORGE_PASSPHRASE	Passphrase for encrypted secrets file

OpenTelemetry tracing (OTel v1, #108)

Forge honors the standard OpenTelemetry SDK environment variables for the observability.tracing subsystem. They sit between forge.yaml and --otel-* CLI flags in the precedence stack — env overrides yaml, flags override env. A set-but-empty env var does not wipe a non-empty yaml value (absence-of-value is "no override").

See Observability — Tracing for the full reference.

Variable	Maps to
OTEL_SDK_DISABLED	inverted → observability.tracing.enabled
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	endpoint (preferred — signal-specific)
OTEL_EXPORTER_OTLP_ENDPOINT	endpoint (generic fallback)
OTEL_EXPORTER_OTLP_PROTOCOL	protocol (http/protobuf or grpc)
OTEL_EXPORTER_OTLP_HEADERS	headers (merged with yaml; env wins on key collision)
OTEL_EXPORTER_OTLP_TIMEOUT	timeout (milliseconds)
OTEL_SERVICE_NAME	service_name
OTEL_RESOURCE_ATTRIBUTES	resource_attrs (merged with yaml)
OTEL_TRACES_SAMPLER	sampler (standard names)
OTEL_TRACES_SAMPLER_ARG	sampler_ratio