Skip to content
Docs menu

Environment variables

The VENOM_* environment variables the CLI reads, what each sets, its default, and the venom.yaml key it overrides.

View .md

Environment variables sit between flags and config files in precedence: a variable beats every venom.yaml, and a flag beats the variable. The config files only fill variables you left unset, so venom config shows env VENOM_MODEL as the source when the variable is set. Keys and tokens are only ever read from the environment (your shell profile or a gitignored .env), never from a config file.

export VENOM_BASE_URL=http://localhost:8787/v1
export VENOM_MODEL=venom-default
export VENOM_THINKING=venom-fast=off,venom-default=low
venom config            # shows "← env VENOM_MODEL" next to model

venom --help prints the CLI's own list of variables.

Variables that match a venom.yaml key

Variable venom.yaml key Default
VENOM_BASE_URL orchestrator.base_url http://localhost:8787/v1
VENOM_MODEL model venom-default
VENOM_FAST_MODEL tiers.fast venom-fast
VENOM_SMART_MODEL tiers.smart venom-smart
VENOM_VISION_MODEL vision_model venom-vision
VENOM_DECISION_MODEL decision_model venom-decide
VENOM_THINKING thinking (merged; the variable wins per model) venom-fast=off,venom-default=medium
VENOM_SEARCH_URL search.url none (DuckDuckGo, no key)
VENOM_SEARCH_ORCHESTRATOR search.orchestrator on
VENOM_SEARCH_RERANK search.rerank off
VENOM_AUTO_TIMEOUT_MS permissions.auto.timeout_ms none
VENOM_AUTO_ON_FAILURE permissions.auto.on_failure ask
VENOM_MAX_WIDTH ui.width auto
VENOM_SERVE_PUBLIC_URL serve.public_url none
BRAVE_API_KEY, TAVILY_API_KEY named by search.brave_key_env, search.tavily_key_env none

Endpoint and keys

Variable What it sets Default
VENOM_API_KEY the bearer key for VENOM_BASE_URL none (no Authorization header)
VENOM_ALIAS_MAP map venom-* aliases to real model ids without an orchestrator: venom-default=qwen3:8b,venom-fast=qwen3:4b auto-mapped when the server lists no venom-* ids
VENOM_MAX_TOKENS_FIELD which request field carries the output cap: max_tokens or max_completion_tokens pi's choice for the model
VENOM_CONTEXT_WINDOW cap on the context window: the smaller of the server-reported window and this; used as is when the server reports none 131072
VENOM_ADMIN_TOKEN the orchestrator admin token: /cost reads the session from the orchestrator, and venom models and the gear wizard's price lookup need it dev-admin-token on loopback
VENOM_ORCH_URL the orchestrator venom models manages VENOM_BASE_URL without /v1 when local, else http://127.0.0.1:8787
VENOM_CLOUD_URL, VENOM_CLOUD_KEY a Venom Cloud deployment and a client key (vck_…); together they win over venom cloud login's saved credentials. Neither set and not logged in: no Cloud traffic none
VENOM_CLOUD_ADMIN_KEY an admin key (vak_…) for publishing org gears from the gear wizard none
VENOM_SERVER_TOKEN the bearer token venom serve requires (16+ characters) none

Behaviour

Variable What it does Default
VENOM_OFFLINE=1 the --offline flag for every command, venom serve and venom acp included: remote MCP servers registered disabled, no web_fetch or web_search off
VENOM_ONLINE=1 let pi make its own startup network calls off
VENOM_DEBUG=1 print harness diagnostics, hook messages and compaction steps off
VENOM_CHROME the browser the browser tools launch the installed Chrome, Chromium, Edge or Brave
VENOM_SOUND_PLAYER your own player command for event sounds (the file is appended), e.g. mpv --no-video the system player
VENOM_POLICY_FILE an organisation policy file, used only where /etc/venom/policy.json doesn't exist none
NO_COLOR turn colour off unset

Paths

Variable What it sets Default
VENOM_HOME venom's state directory; the home config is $VENOM_HOME/config.yaml ~/.venom
VENOM_CODING_AGENT_DIR the agent config directory (pi's settings, agents, skills) ~/.venom/agent
VENOM_CODING_AGENT_SESSION_DIR where sessions are saved <agent dir>/sessions
VENOM_TOOL_DIRS directories searched first for language servers and formatters (PATH-style) none
VENOM_NODE the node binary the release launcher runs venom with the bundled one

Orchestrator variables

The orchestrator is a separate process with its own variables. Two of them share the config vocabulary:

Variable Read by What it sets Default
VENOM_CONFIG the orchestrator and venom-daemon the path of orchestrator.yaml (upstreams, routes, route profiles). The CLI never reads it; venom.yaml has no variable for its path config/orchestrator.yaml
VENOM_MODEL_CATALOG the orchestrator the directory of model-catalog shards served at GET /api/models/providers/{id} model-catalog/ next to VENOM_CONFIG

The Orchestrator section documents the rest of its variables.