Environment variables
Environment variables
This is the single source of truth for the bridge environment variables.
| Variable | Provider | Default | Purpose |
|---|---|---|---|
GEMINI_API_KEY |
Gemini | unset | Google AI Studio key. Set, it routes advisory Gemini calls to the Gemini API (providers.gemini.transport auto). Never passed to agy |
GOOGLE_API_KEY |
Gemini | unset | Read only with providers.gemini.transport: "api", when GEMINI_API_KEY is unset. Does not switch auto |
GEMINI_API_BASE |
Gemini | https://generativelanguage.googleapis.com/v1beta/openai |
API endpoint override for the key path (mainly for tests) |
GEMINI_DEFAULT_MODEL |
Gemini | auto-gemini-3 |
agy path: default model when neither the call nor providers.gemini.model sets one |
GEMINI_DISABLE_TIMEOUT_RECOVERY |
Gemini | unset | 1 forces legacy timeout (no drain) |
GEMINI_MIN_ANSWER_CHARS |
Gemini | 1 |
Minimum trimmed stdout length for a clean exit to count as an answer; shorter output, or a reply under 400 chars that only announces intent ("I will begin by..."), fails as empty (see Answer floor). 0 disables both checks |
AGY_BIN |
Gemini | agy |
Override the path to the agy binary |
AGY_LAST_CONVERSATIONS |
Gemini | ~/.gemini/antigravity-cli/cache/last_conversations.json |
Override the conversation-id map file (mainly for tests) |
XAI_API_KEY |
Grok | unset (required) | xAI API key; missing key returns missing-auth |
GROK_DEFAULT_MODEL |
Grok | grok-4.6 |
Default model when neither the call nor providers.grok.model sets one |
XAI_API_BASE |
Grok | https://api.x.ai/v1 |
API endpoint override |
GROK_REASONING_EFFORT |
Grok | high |
low/medium/high; none or off omits the field. Overridden by providers.grok.reasoningEffort (providers.grok.consensusReasoningEffort during consensus) |
GROK_FILE_TTL_SECONDS |
Grok | 604800 (7 days) |
Upload lifetime, clamped 1h..30d |
GROK_UPLOAD_TIMEOUT_MS |
Grok | 120000 |
Ceiling for one Files API upload (separate from the answer timeout). 0 disables it |
GROK_STREAM |
Grok | unset (streaming on) | 0 forces the legacy non-streaming request, which reinstates undici's 300s transport ceiling (see Grok streaming) |
GROK_MIN_ANSWER_CHARS |
Grok | 1 |
Minimum trimmed answer length; shorter text, or a reply under 400 chars that only announces intent ("I'll verify the cited files..."), fails as empty (see Answer floor). 0 disables both checks |
DELIBERATION_SESSIONS |
sessions | <XDG cache>/deliberation/sessions |
Override the session store directory (see Session persistence) |
CODEX_BIN |
Codex | codex |
Override the path to the codex binary (see Windows CLI resolution) |
CODEX_ACCESS_TOKEN |
Codex | unset | Codex access token (ChatGPT Business/Enterprise workspaces only), read by codex-cli itself. It never refreshes, so the same value works on every machine and in every web session until it expires. codex ranks it above auth.json. It counts as a credential for codexHealth(), and while it is set CODEX_API_KEY is dropped from the child's env |
CODEX_API_KEY |
Codex | unset | Codex API key, used ONLY when there is no ChatGPT credential (codex login = $CODEX_HOME/auth.json / ~/.codex/auth.json, or CODEX_ACCESS_TOKEN). With one, the provider drops the key from the codex exec child's env so the subscription wins. OPENAI_API_KEY is never used for codex and is always dropped from the child's env |
MCP_TOOL_TIMEOUT |
host (all) | unset | Set by some MCP hosts (Claude Code on the web: 60000) - the host kills any tool call longer than this. Deliberation reads it and clamps every provider ceiling to MCP_TOOL_TIMEOUT - 5000 ms so the call fails as a timeout naming the cap; see Timeouts. Claude Code applies a per-server timeout ahead of this variable, so .claude-plugin/plugin.json sets 1800000 on every server and mirrors it into the server env under this name (the mirror is what the clamp reads) |
DELIBERATION_RUNS |
dashboard | <XDG cache>/deliberation/runs |
Override the dashboard run journal directory (see Dashboard); only written when dashboard.enabled |
DELIBERATION_DEBUG_LOG |
debug | <XDG cache>/deliberation/debug.jsonl |
Override the debug log path (see Observability); only written when debug.enabled |
Codex has no bridge and no MCP server of its own: the core provider
(core/providers/codex.js) spawns codex exec and lets the CLI read ~/.codex/config.toml
directly. CODEX_BIN above overrides which binary is spawned. The model and reasoning
effort can be pinned in config.json as providers.codex.model and
providers.codex.reasoningEffort (none/minimal/low/medium/high/xhigh/max/ultra), as well as providers.codex.consensusReasoningEffort (for /consensus and consensus-step). They are
passed as --model <id> and -c model_reasoning_effort="<value>", so they win over
~/.codex/config.toml. Unset, codex uses that file. Precedence for reasoning effort: per-call reasoningEffort tool argument, then
providers.codex.reasoningEffort (or providers.codex.consensusReasoningEffort during consensus), then
providers.defaults.reasoningEffort (or providers.defaults.consensusReasoningEffort during consensus),
then ~/.codex/config.toml. Each value
is checked against a closed shape (model ^[A-Za-z0-9][A-Za-z0-9._:/-]*$, effort from the enum)
before it reaches argv, so a value starting with - or carrying a quote is dropped and never
becomes a flag or a TOML injection. Results report the pinned model and effort ("default" /
null when unpinned). See SETUP.md.
Codex per-call timeout. The core Codex provider caps each codex exec invocation to
CODEX_DEFAULT_TIMEOUT_MS (600 000 ms, 10 min) by default, so a stalled Codex process cannot
block a consensus round indefinitely. Raise or lower it with providers.codex.timeout (or
providers.defaults.timeout); a per-call timeout is not exposed through the MCP tool surface.
Codex credential. A ChatGPT credential always wins. codexEnv() builds the child's env
with this rule:
CODEX_ACCESS_TOKENis set (a ChatGPT Business/Enterprise access token), or$CODEX_HOME/auth.json/~/.codex/auth.jsonexists (codex login, usually a ChatGPT subscription): codex uses it, andCODEX_API_KEYis dropped from the child's env. codex-cli ranks that env var above both, so leaving it in would silently bill the API instead. Between the token and the login, codex's own order applies (the token first).- No ChatGPT credential:
CODEX_API_KEYis passed through as-is. OPENAI_API_KEYis never used and never reaches the child.
Rule 3 replaces an earlier forward of OPENAI_API_KEY as CODEX_API_KEY. On a machine that
exports OPENAI_API_KEY for other tools, that forward beat the ChatGPT login, so every GPT call
was billed to the API key and failed with You have no credits remaining once its credit ran
out. A host that exports only OPENAI_API_KEY must now run codex login, set
CODEX_ACCESS_TOKEN, or set CODEX_API_KEY.
The provider's health() (codexHealth()) is stat-only: the CLI must be on PATH and
CODEX_ACCESS_TOKEN, a login auth.json, or CODEX_API_KEY must exist. Otherwise the panel
lists codex as unavailable with that reason and does not dispatch to it.
One login per machine. A ChatGPT login's refresh token works once. codex refreshes about 8
days after last_refresh (or on a 401), writes the new pair to auth.json, and the old refresh
token is dead. A copy of that file on a second machine (a web container seeded from a laptop, a
setup script restoring it from a secret at every session start) therefore fails as soon as either
side refreshes, with Your access token could not be refreshed because your refresh token was already used. Please log out and sign in again. Nothing in that text says "auth" or "login", so
classifyCodex() also matches access token could not be refreshed, the phrase all four of
codex's refresh failures share. It matches that exact phrase, reads stderr only, and consumes
each line of the prompt it sent ONCE as echo (so the same line printed again by codex still
counts): codex exec echoes the prompt to stderr, a prompt
about token code says "refresh token" freely, and one may even quote this exact phrase. A
bare match would turn a rate limit into a non-retryable auth and, with login on first use,
start a needless device login.
The result is errorKind: "auth" (not retried), and the message STARTS with codex's own line and
the fix, then the full output: codex prints its banner and the whole echoed prompt on stderr
before the error, so the line would otherwise sit far below them. The hint is added only when
the result is auth, so the kind and the message never disagree. stat cannot see this state
(the file exists and parses), so health stays ok. Setup per host:
SETUP.md - Claude Code on the web.
Login on first use. The unified server builds the codex provider with deviceLogin: true
(the library default is off). Two states start a device login: no credential at all, and a
spent login (the refresh failure above). Instead of failing, ask() then:
- Starts
codex login --device-auth(same binary resolution and env scrub ascodex exec; waiting for its code is bounded by half the host budget left, and a call that runs out returns "no code yet" while the shared login keeps going for the next call) and parses the link, the one-time code and its lifetime from codex's output (parseDevicePrompt). That output is text for humans, so the match is loose: the link is the URL with/devicein its path (codex may print an update notice with its own URL first), and only anopenai.com/chatgpt.comhost (or a subdomain) is ever offered as the link. Both must be followed by whitespace, so output split across pipe chunks never yields a partial code. If no such link and code appear within 20s, the result carries codex's own output instead; once a code is shown, that timer is off. A code nobody used is reaped 5s after it expires, whatever codex does. One login per process (makeDeviceLogin): a second caller while the code is valid gets the same code; an expired or finished login is replaced. The login runs in its own process group (detachedon POSIX;taskkill /Ton Windows) and is always killed as a tree: an npm install runs a Node launcher that starts the native binary, and killing only the launcher would leave the real login polling. When stdin closes (MCP stdio shutdown) or on SIGTERM/SIGINT the server kills every running login AND refuses new ones, since a codex run still in flight could otherwise hit a spent login afterwards and start one nobody sees;exitkills them too. - Asks the host to show the code (
confirmLogin). The server negotiates the client's MCP protocol version (up to2025-11-25) and records itselicitationcapability atinitialize. Elicitation is sent only on a negotiated2025-06-18or later; URL mode only on2025-11-25or later withelicitation.urldeclared (elicitation/createwithmode: "url", the link, and the code in the message); otherwise a form whose message carries both. One code raises one dialog, however many calls join it. The dialog is never awaited. It is sent and the call returns; its outcome belongs to the LOGIN, not to the call:acceptsimply lets the shared login land,declineends that login whenever the refusal arrives, anything else is ignored. A dialog that is already stale before it goes out is never sent at all (the signal is checked first), and one that is open lives at most as long as its code: a settled login aborts it and the server sendsnotifications/cancelled. One code raises one dialog, so repeated calls cannot pile them up on the host. A decline is scoped to ITS OWN login: a refusal can arrive long after that code was replaced, and killing the login that took its place would revoke a code the user is holding. A decline that arrives AFTER the login landed can only end the process, not the credential: the call returned long ago, so there is no channel left to report it. The dialog therefore says up front that declining ends the login and thatcodex logoutundoes one already approved in the browser. Deliberation never deletes a credential file itself. A settled login (landed or dead) makes the dialog stale, so the server then sendsnotifications/cancelledand the host can close it. Both the dialog and the result text carry a line saying the code signs this machine's codex into the user's ChatGPT account, the same warning codex prints. - Returns
errorKind: "auth"as soon as codex prints the code, typically ~1 s and at mostDEVICE_PROMPT_WAIT_MS(20 s). The message puts the link and the code each alone on a line, blank lines around them, so both are one copy; the lifetime it quotes is what is actually left (~15 min). The user approves in the browser and re-runs; the shared login keeps polling, so the next call findsauth.jsonand answers. With no dialog, a dismissed dialog, an error or a timeout, it returnserrorKind: "auth"whose message starts with the link and code (codex's refresh line, if any, follows). The login keeps polling in the background, so the next call after the user approves simply findsauth.json. A login that ended without landing is reported as such, never with its dead code, and the next call starts a fresh one. The login child is killed when the server process exits.
codex-login tool and /deliberation:codex-login. Login on first use depends on the agent
actually making a GPT call. In a real web session it did not: the agent read codex.js,
decided a logged-out call "would only return the device-auth link, not an answer", and
answered from local config, so the login never started. The codex-login tool runs the same
signIn path with no question (provider.login(); it never runs codex exec) and returns
{ status: authenticated|pending|starting|failed|unavailable, message, url?, code?, expiresAt? }; ask()'s auth results carry the same object as deviceLogin. It joins the one
shared login, so it and ask-gpt always show the same code. It is unavailable when codex is
not on this server, is disabled in config, or fails its health check (no CLI). The command
files and the ask-gpt / ask-one tool descriptions also say never to skip a GPT call
because GPT looks logged out; /deliberation:doctor and the session-hook text point at
/deliberation:codex-login. panel and health stay side-effect-free: a login is never started by
a probe.
Login before the fan-out (panel.needsLogin). Login on first use still cost the first
run: /ask-all synthesized without GPT, and in /consensus a codex voice that errors every
round is dropped by the circuit breaker, so the user had to remember /deliberation:codex-login
before every web session. codex.health() now returns { ok: true, needsLogin: true } in
that case, and panel reports the panel members that carry the flag as needsLogin[]
(for: "consensus" echoes the consensus panel). /ask-all, /consensus and /ask-gpt read it
first: they call codex-login, print the link and code, ask the user to approve
(AskUserQuestion), call codex-login again to confirm authenticated, and only then
dispatch. The login still starts in a command the user ran, never in the probe, so the
15-minute code is spent on the run that asked for GPT (the reason a SessionStart login was
rejected). stat cannot see a spent auth.json, so the in-call login stays as the fallback.
Health treats "no credential" as ok while deviceLogin is on: that is the one gap ask()
closes itself, so GPT stays on the panel and delivers the code. consensus-step's
dispatch_peers now includes an errored voice's message (bounded plain text, plainMessage)
so the code reaches /consensus; the command files tell Claude to show it as-is. The link
and code never go to the debug log or the session store. A host that neither supports
elicitation nor shows tool errors still gets the code in the result text.
Timeouts and retries. See Timeouts for the full precedence ladder
(providers.defaults.timeout is the one knob that covers every provider) and
Retries for which error kinds are retried.