Environment Variables Reference

Every environment variable Plan Forge reads, grouped by subsystem, with type, default, scope, and security note. The companion reference to Appendix T — .forge.json: settings that change per-machine or contain secrets live here; settings that travel with the project live there.

Orientation

Plan Forge reads roughly 40 environment variables across nine subsystems. Most have sensible defaults; the only ones you typically set yourself are provider API keys (so the orchestrator can call a model) and server ports (if 3100/3101 conflict with something else on your machine).

Every field row uses the same six columns, Variable, Type, Default, Scope, Set when, Security, so the table reads the same way no matter which subsystem you land on. Scope is one of per-user (export in your shell profile), per-machine (system env or CI variable), or per-session (transient, set on a single invocation).

Provider API keys

The orchestrator needs at least one of these to route a slice through a non-Copilot model. All are read from the environment first, then from .forge/secrets.json as a fallback (see pforge-mcp/secrets.mjs for the loader). The dashboard Config → Secrets tab is the friendliest way to set them, it writes the secrets file atomically and never echoes the value back.

Azure OpenAI (alternative routing)

Set this group when your organization routes model calls through Azure OpenAI for billing, residency, or governance reasons. The keys are read by cost-service.mjs for pricing, by the orchestrator for invocation, and by forge_doctor_quorum for quota preflight (when PFORGE_FOUNDRY_QUOTA_PREFLIGHT=1).

Server ports and network

Set these only if the defaults collide with something else on your machine, or when you need to harden the dashboard bridge with an auth token.

Project and runtime

Mostly read internally. PLAN_FORGE_PROJECT is the only one you might set yourself, and almost always only in tests.

Orchestrator timing

Tune these only when defaults are biting, usually on slow CI runners or when a long-running gate (large vitest suite, integration test, browser test) hits the wall.

Feature toggles

Opt-in switches for experimental subsystems and bypasses for hardening rails. Most users never touch these.

Telemetry (OpenTelemetry)

Standard OTel variables. When OTEL_EXPORTER_OTLP_ENDPOINT is set, the MCP server auto-enables tracing and ships spans to the configured collector. See Compliance & Data Residency — Observability Export for the full collector setup.

Host detection (read-only)

Plan Forge reads these to figure out which IDE or agent CLI is hosting it, so the orchestrator can pick the right routing default and the right model surface. You should never set these yourself, they are populated automatically by the host. Listed here for transparency only.

CLI internal (set transiently by pforge)

These variables are set by the CLI or the orchestrator for the duration of one invocation and then unset. Do not set them in your shell profile, they are documented for transparency and for users writing extensions.

Resolution precedence

When a setting has multiple sources, the orchestrator resolves in this order, first one that yields a non-empty value wins:

1. CLI flag on the running command (e.g. --quorum=power).
2. Plan front-matter directive in the plan being executed (e.g. Model: claude-opus-4.7).
3. Environment variable set in the shell or by the host (most of this appendix).
4. .forge/secrets.json for the keys listed in the Provider API Keys table.
5. .forge.json for the keys listed in Appendix T.
6. Built-in default baked into orchestrator.mjs or capabilities.mjs.

One concrete example. OPENAI_API_KEY is resolved by checking process.env first, then falling back to .forge/secrets.json#OPENAI_API_KEY. The dashboard's Config → Secrets tab writes the latter; CI runners typically rely on the former. Both work; the env-var wins when both are set.

Worked example

A representative shell setup for a developer on Windows running a hybrid Azure-OpenAI / Anthropic stack with the dashboard on a non-default port:

# Provider keys (better: store in .forge/secrets.json)
$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:OPENAI_API_KEY    = "sk-..."

# Azure OpenAI alternative routing
$env:AZURE_OPENAI_ENDPOINT      = "https://contoso-aoai.openai.azure.com/"
$env:AZURE_OPENAI_API_VERSION   = "2024-02-01"
$env:AZURE_OPENAI_DEPLOYMENT_TYPE = "global"
$env:AZURE_AUTH_MODE            = "managed-identity"

# Non-default ports (3100/3101 conflicted with another local service)
$env:PLAN_FORGE_HTTP_PORT = "3110"
$env:PLAN_FORGE_WS_PORT   = "3111"
$env:PFORGE_DASHBOARD_PORT = "3110"

# Tracing to a local OTel collector
$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318"
$env:OTEL_SERVICE_NAME           = "plan-forge-mcp-dev"

# Lift gate timeout for a long-running integration suite
$env:PFORGE_GATE_TIMEOUT_MS = "600000"   # 10 minutes

See also

• Appendix T — .forge.json Reference, the per-project config file that pairs with this appendix.
• Customization — Configuration Hierarchy, how .forge.json, env vars, and instruction files interact when settings conflict.
• MCP Server Reference — REST API, the dashboard's HTTP surface, including the bearer-token auth flow that PFORGE_AUTH_TOKEN gates.
• pforge-mcp/secrets.mjs, the loader for .forge/secrets.json and the canonical source for the provider-key whitelist.
• Troubleshooting — Common Errors, recovery hints for ERR_NO_API_KEY, ERR_TESTBED_NOT_FOUND, and the gate-timeout family.