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.