Environment variables
The VENOM_* environment variables the CLI reads, what each sets, its default, and the venom.yaml key it overrides.
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 modelvenom --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.
Related
- Configuration: files, precedence and trust.
- venom.yaml reference.