Skip to content

Environment Variables

Only variables that change Pantheon behavior are listed. Test-only and internal diagnostic variables are not user knobs. Values are read at process start unless noted.

Installer and generation

Variable Default Purpose
OPENCODE_VERSION unset v2 pins the host gate and skips the probe. Any other value — including v1 — is refused.
OPENCODE_BIN opencode Host binary used for the --version probe. A basename of opencode2 resolves to 2.x without probing.
OPENCODE_V2_SPEC @opencode/cli@latest Sandbox spec that provides the opencode2 binary.

The host gate is described once in Compatibility.

Sandbox runs

Variable Default Purpose
PANTHEON_SANDBOX_ROOT ~/pantheon-sandbox Isolated sandbox root. Refused if unsafe for --reset.
PANTHEON_SANDBOX_MODEL opencode-go/mimo-v2.5 Model used by init and the prompt battery.
PANTHEON_PROMPT_TIMEOUT 300 Per-prompt timeout in seconds.

Sandbox mechanics are in Release Process.

Paths and storage

Variable Default Purpose
PANTHEON_HOME unset Overrides the config root used for memory and the price cache. Resolution is PANTHEON_HOME, else $XDG_CONFIG_HOME/opencode, else ~/.config/opencode.
XDG_CONFIG_HOME ~/.config Used when PANTHEON_HOME is unset.
XDG_STATE_HOME ~/.local/state User state root for the separate local decision-budget SQLite ledger.
PANTHEON_PROJECT unset Absolute project root for project-first resolution (code mode, persistence). A relative value is rejected where an absolute path is required.
PANTHEON_HOOKS_LOG <project>/.pantheon/logs/hooks.log Overrides the plugin hook log path.

Memory

Variable Default Purpose
PANTHEON_MEMORY_MAX_ENTRY_BYTES 65536 Per-entry serialized size cap for memory_store. Any positive integer; an invalid value falls back to 64 KiB. Read per write.

Memory policy is in Memory.

Cost

Variable Default Purpose
PANTHEON_NODE node from PATH Node >= 22.5 binary used only for the node:sqlite capability in the CLI fallback. Must exist and be executable.
PANTHEON_COST_OFFLINE unset Set to 1 to forbid every network request, including refreshPricing: true. No socket is opened.
PANTHEON_COST_DB unset Absolute path to the cost database, checked before OPENCODE_DB.
OPENCODE_DB unset Absolute path to the cost database, checked before the XDG default.
PANTHEON_OPENCODE_VERSION unset v1 or v2 narrows an already-detected schema to one table family. It does not select a file.

Backend resolution and report dimensions are in MCP Tools.

Vision

Variable Default Purpose
PANTHEON_VISION_MODEL unset Highest-precedence vision model pin. An explicit pin that does not qualify (non-Zen, text-only, or absent from the catalog) is discarded and automatic selection takes over.
PANTHEON_OPENCODE_API_KEY unset OpenCode Zen credential for native vision and the vision MCP.
OPENCODE_API_KEY unset Shared fallback credential for Zen endpoints.
PANTHEON_VISION_TOOL unset Opts into the Bifrost vision tool; Bifrost is never the default.

Model precedence and the degradation chain are in MCP.

Models

Variable Default Purpose
PANTHEON_MODEL_PRESET unset Legacy preset selector. The runtime ignores static presets and applies only explicit per-agent project overrides.

Local decision recommendation

Variable Default Purpose
PANTHEON_LOCAL_DECISION_ROUTER unset (disabled) Set to 1 to enable only the standalone local advisory API. It does not enable provider transport, host dispatch, or permissions.

The API contract and its abstention behavior are in Local Decision Router.

Decision layer flags (shadow adapters)

All four flags are read once when the plugin registers, so changing any of them needs a host restart. None is set in a default install; anything other than the listed truthy values leaves the feature off.

Variable Default Purpose
PANTHEON_V2_P7_LOOP unset (off) 1, on or true enables the P7 loop adapter on session.execution.succeeded. It counts executions and writes effect: none observations to an in-memory, bounded collector that the plugin never reads back (it is exposed only to tests); it does not enforce loop limits. The 12-execution cap (P7_LOOP_MAX_EXECUTIONS) is advisory: no measured host surface signals a new user turn, so the streak is not claimed to reset.
PANTHEON_V2_P8_GUARDRAIL unset (off) 1, on or true would enable the P8 guardrail on permission.evaluate only. It can only narrow, and it remains off: C8 closed by measurement, and the verdict is that the declared rules match no delivered payload, so the point is recorded as advisory and narrows nothing. A written deny is honoured by the host, but no declared rule can produce one. execute.before remains the only hard barrier.
PANTHEON_J1_RISK_SCORE unset (off) 1, on or true enables the J1 risk-score shadow gate on execute.before for write/execute tool calls (bash/shell and webfetch, file writes). Each observed call fires ONE bounded native Jev decision through the same gate chain as pantheon_jev_decide (config, consent, budget reservation, decision.egress permission) and records effect: none shadow records (reason tokens like risk-3-intent-yes, skip-timeout) to the in-memory, bounded collector the plugin never reads back. The request carries no user content: tool name token, scope class and the tool input's sha256 only. Fail-open on every failure mode; fired without awaiting the hook, self-bounded at 2s, never retried. Shadow never blocks — the only reachable verdict is observe. See V2 Native Decisions.
PANTHEON_J3_ESCALATION unset (off) 1, on or true enables the J3 turn-complexity escalation shadow classifier on execute.before for delegate dispatches (the native subagent tool). Each dispatch fires ONE bounded native Jev decision through the same gate chain as pantheon_jev_decide (config, consent, budget reservation, decision.egress permission) asking one score question ("complexity of this delegation", 2–10 levels) and records effect: none shadow records (reason tokens like esc-cheap-c2, esc-main-c-na, skip-timeout). The request carries no user content: delegate agent token, Brief sha256, Brief length and the local risk-word flag only — the Brief text never leaves the machine. Local rails (risk words, user-pinned model, >8,000-char Brief) and every unsure or timed-out answer force the main model. Shadow only: the recorded verdict never changes the dispatched model in this phase — the per-agent override mechanism exists behind a tested seam for a separately reviewed activation. Fired without awaiting the hook, self-bounded at 2s, never retried. See V2 Native Decisions.

Shadow points (P1, P2, P3, P9, P11) have no environment switch: there is no behaviour to switch. P1 and P2 are registered on session.hook('prompt') and observe a projection of the admission payload carrying only prompt.agents and prompt.skills — no text, no file bytes, no metadata. P3 is registered at its declared tool.invoke: the pantheon_local_decision tool hands the adapter its own input, which carries complexity and gateStatus, so it records a classification when the tool is invoked. P9 is registered on session.hook('compaction') and reads the measured carrier only — the top-level sessionID and the system parts — pushing nothing into the injected context. P11 is registered inside ctx.tool.transform and reads the draft the host hands it without calling any mutator. Each record says effect: none and goes to an in-memory, bounded collector that the plugin never reads back (exposed only to tests). They cannot deny, delay or mutate admission; P2 stays advisory and never filters.

The remaining four — P4, P5, P6 and P10 — have no production call site: no production file imports them. Their adapters are constructed only by their per-point test suites (v2-decision-p4.test.ts … v2-decision-p11.test.ts). P6 and P10 declared the prompt hook, but that payload carries neither council candidates nor counsellor claims; P4 needs a memory candidate array and the measured context payload carries system text parts instead; P5 needs a declared { requirements, responses } pair and the execute.after event carries neither. They are unwired rather than recording a refusal from a surface that cannot feed them. On a host they do not read the turn, record no telemetry and change nothing — not because they are disabled, but because nothing constructs them. Coverage and unmeasured surfaces are in Local Decision Router.

Decision-provider credentials

There is no Pantheon-owned decision transport. The only egress surface is the host's native Decisions API, invoked by the explicit pantheon_jev_decide tool behind the user-level config, budget, and permission gates — see V2 Native Decisions. The variables below are listed because decision-router code mentions them; none is read on a production path.

Variable Default Purpose
OPENAI_API_KEY unset Not read anywhere. Direct OpenAI has no native Decisions route and is never substituted.
TYPESAFE_API_KEY unset Not read anywhere. The native TypeSafe route uses host-owned /connect credentials, never a Pantheon env read.
OPENCODE_API_KEY unset Not read by the decision router for OpenCode Console/Free; the native route uses the host's own Console auth. It remains in use by other documented OpenCode integrations.

There is no configurable base URL, retry, failover, or fan-out switch, and caps have no defaults. The request bound (one bounded text state, 1–4 typed questions) lives in the native request preparer; a denied host permission means zero requests.

Runtime-specific

Variable Default Purpose
OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS unset Experimental gate for some runtimes; set by Pantheon's npm run start launcher. It is not a universal prerequisite and does not create a missing tool.

What is not here

Local Promptfoo/evaluation experiments are development-only: place them under evals/promptfoo/, which is gitignored and excluded from packaging, package evidence, CI tests, coverage, and release gates. Publish reviewed findings as documentation, not the harness, datasets, outputs, or credentials.