docs

Environment variables

Environment variables sit between CLI flags (highest) and the config file (lowest) in the precedence order. Everything below is what the daemon resolves at start; dex doctor prints each value with its origin.

Providers & selection

Variable	Description
`OPENCODE_API_KEY`	API key for the opencode gateway (required for `opencode`; export it in your shell profile).
`ANTHROPIC_API_KEY`	API key for the built-in `anthropic` provider (`model: anthropic/<model>`); resolves cache-less.
`DEX_MODEL`	Model selection, `provider/model` (`endpoint/model` works too) — the same knob as the file's `model:` key. A bare provider name has no model and is rejected.
`DEX_PROVIDER`	Not supported. Model selection is `DEX_MODEL=<provider>/<model>`.
`DEX_MODELS`	Comma-separated models for `/model` autocomplete (default: catalog cache).
`DEX_THINKING_EFFORT`	Default reasoning effort (a stored `/thinking` choice wins; file `thinking_effort:` is the fallback).
`DEX_SYSTEM_PROMPT`	Replace the built-in base system prompt (same knob as file `system_prompt:`; project/extensions/skills still append).
`DEX_SYSTEM_PROMPT_FILE`	Read the replacement base system prompt from a file (same knob as file `system_prompt_file:`).
`DEX_MODEL_APIS`	Per-model wire protocol table (`id=api,…`; full `endpoint/id` key beats bare id).
`CODEX_ACCESS_TOKEN` / `CODEX_ACCOUNT_ID`	Optional Codex OAuth access-token override + paired account id.
`CODEX_HOME`	Directory holding Codex `auth.json` (default `~/.codex`).

Headers

Variable	Description
`DEX_HEADERS` `OPENAI_HEADERS` `ANTHROPIC_CUSTOM_HEADERS`	Extra provider headers (JSON object or `Name: Value` pairs, comma/newline separated; later var wins: `ANTHROPIC_` < `OPENAI_` < `DEX_*`). File `headers:`/`http_headers:` < env < `--header`. `authorization` can't be overridden. `OPENAI_HEADERS`/`ANTHROPIC_CUSTOM_HEADERS` are deprecated aliases — use `DEX_HEADERS`.

HTTP & tools

Variable	Description
`DEX_HTTP_CONNECT_TIMEOUT_SECS`	HTTP connect timeout (default 10).
`DEX_HTTP_REQUEST_TIMEOUT_SECS`	Total request bound, applied only when explicitly set — streaming LLM/chat paths default to no total timeout so long turns aren't killed.
`DEX_STREAM_IDLE_TIMEOUT_SECS`	SSE idle watchdog: no chunk (or keep-alive) for this long counts as a stall (default 90, 300 for reasoning-capable models; `0` disables). Pre-output stalls and dropped connections retry automatically same-protocol (2 retries) before failing the turn. Also scales the socket-level per-read backstop (default 330 s, override +30 s) so the watchdog always fires first; `0` disables the backstop too.
`DEX_TOOL_TIMEOUT_SECS`	Shell command timeout in seconds (default 120).
`DEX_TOOL_OUTPUT_BYTES`	Maximum captured stdout/stderr bytes per stream (default 1 MiB).
`DEX_MAX_TOOL_ITERATIONS`	Per-turn cap on tool rounds — one round per assistant batch with calls, not per call (default 200). A looping model is stopped with partial progress preserved and a transcript marker.
`DEX_TOOL_CACHE`	`1` to cache tool results across runs (`dex-tool-cache.json`; default off).
`DEX_VERIFY`	Verification hook: `1` auto-detects `cargo test`/`go test`/`npm test`; or set to a command. Off by default.

Permissions & daemon

Variable	Description
`DEX_PERMISSION`	Tool permission ceiling (`read-only`, `ask`, or `trusted`; default `trusted`). Legacy `ask-writes`/`ask-shell` values map to `ask`.
`DEX_DAEMON_TOKEN`	Bearer token for the daemon API. Required by clients when `dex serve` binds a non-loopback address (auto-generated and written to `$XDG_DATA_HOME/dex/daemon.token`, 0600) or when the operator sets one. Loopback-only daemons need no token.

Logging

Variable	Description
`DEX_LOG`	Runtime log level: `off`, `error`, `warn` (default), `info`, `debug`, `trace` — works on release builds. Logs go to stderr, or to `$XDG_DATA_HOME/dex/dex.log` while the TUI runs. `debug` covers provider requests/responses and tool runs; `trace` adds raw provider SSE lines.

Compaction & context

Variable	Description
`DEX_COMPACTION`	`llm` for LLM summarization (`1` accepted), `jev` for verbatim tool-output pruning (default deterministic). The deprecated `DEX_COMPACTION_LLM=1` still selects `llm` with a one-time warning.
`TYPESAFE_API_KEY`	Enables the Typesafe Jev scorer for `DEX_COMPACTION=jev` (needs the config `jev:` opt-in table).
`TYPESAFE_JEV_URL`	Override the Jev evaluation endpoint.
`DEX_CONTEXT_WINDOW`	Override model context window (file `context_window:` > catalog when unset; unknown models with neither are a startup error).
`DEX_RESERVE_TOKENS`	Tokens reserved for reply (default 16384).
`DEX_KEEP_RECENT_TOKENS`	Recent tokens kept on compaction (default 20000).
`DEX_COST_PER_1K`	Fallback token cost per 1k tok (prompt + completion) for the status-bar spend figure when the pricing catalog has no entry (default `0.002`).

Gated features

Variable	Description
`DEX_SUBAGENTS`	`0` to unregister the `delegate` tool (default on in daemon sessions).
`DEX_AGENT_WAKE`	`0` to disable idle wake turns (default on): when a child agent completes while the session is idle and a client is listening, the daemon runs one wake turn to surface the notice.
`DEX_AGENT_WAKE_DEBOUNCE_MS` / `_RETRY_MS` / `_RETRIES` / `_PRESENCE_MS`	Idle-wake cadence overrides: completion-burst debounce (default 2000 ms), retry delay while a user turn is live (default 5000 ms), retry count (default 12), client-presence window (default 30000 ms).
`DEX_CACHE_WARMING`	`0` to disable prompt-cache warming (default on): after a completed turn, the daemon re-sends its last request once before the provider's ~5-minute prompt cache expires, so the next turn reads the context at cache-hit price. Anthropic-native models only; pings are gated on estimated savings (≥ $0.05) and never enter the session.

Other opt-in knobs (DEX_VERIFY, DEX_AUDIT, DEX_DURABLE, DEX_COMPACTION) are listed above; see the experiments guide for the full tour.

MCP & extensions

Variable	Description
`DEX_MCP_SERVERS_JSON`	MCP servers as JSON (same shape as `mcp_servers:` in config; wins over the file, handy for tests).
`DEX_MCP` / `DEX_NO_MCP`	`0`/`off`/`false`/`no` (or `DEX_NO_MCP=1`) disables all MCP servers.
`DEX_MCP_MAX_TOOLS`	Cap on merged MCP schema tools (default 200; head kept sorted by name).
`DEX_EXTENSIONS_PATHS`	Extra Lua-extension dirs (`:`-separated; user scope). Wins over `extensions.paths:` in config.

Durability, paths & updates

Variable	Description
`DEX_DURABLE`	`1` to `fsync` every session line (default only `turn_`/`effect_`).
`DEX_AUDIT`	`1` to write `audit.jsonl` per tool call (default off; session already journals).
`DEX_CONFIG`	Override the config file path (default `$XDG_CONFIG_HOME/dex/config.yaml`).
`DEX_REPO`	GitHub repo `dex update` downloads releases from, `owner/name` (default `sumofbytes/dex`).
`DEX_VERSION`	Version pin for `dex update`: `vX.Y.Z` (bare or `V`-prefixed also accepted) installs that exact release, enabling downgrades; `latest` (default) follows the newest release. Both also honored by `scripts/install.sh`.
`XDG_CONFIG_HOME` / `XDG_DATA_HOME` / `XDG_CACHE_HOME`	XDG base dirs for config/data/cache.
`HOME`	Fallback when XDG vars are unset.