Environment variables
Every environment variable the venom CLI, the harness and the dev stack read, with what it does and its default.
venom reads its settings from flags, then environment variables, then venom.yaml files, then built-in defaults. This page lists the variables. The orchestrator's own variables (upstream keys, VENOM_ADMIN_TOKEN, VENOM_LISTEN, mesh mode) are listed in the orchestrator section; the ones here are read by the CLI, the harness library, venom serve, and the dev stack's compose file and scripts.
A minimal setup needs at most three:
export VENOM_BASE_URL=http://localhost:8787/v1 # any OpenAI-compatible endpoint, including /v1
export VENOM_API_KEY=sk-… # if that endpoint needs a key
export VENOM_MODEL=venom-default # the model or alias to use
venom doctor # shows what venom resolved, and from wherevenom --help prints a short version of the tables below. In a checkout, make env copies .env.example to .env, which make targets and compose read; the CLI itself reads only its process environment.
Endpoint and models
| Variable | What it does | Default |
|---|---|---|
VENOM_BASE_URL |
The OpenAI-compatible endpoint, including /v1. |
http://localhost:8787/v1 |
VENOM_API_KEY |
Bearer key for that endpoint. | none (no Authorization header) |
VENOM_MODEL |
The model the main agent uses. | venom-default |
VENOM_FAST_MODEL |
The fast tier: the explorer subagent, agents with model: fast, summaries. Same as models.fast in venom.yaml. |
venom-fast |
VENOM_SMART_MODEL |
The smart tier: agents with model: smart. Same as models.smart. |
venom-smart |
VENOM_VISION_MODEL |
The model that describes pasted images for a text-only model. | venom-vision |
VENOM_ALIAS_MAP |
Client-side alias map for endpoints that do not serve venom's venom-* aliases, as alias=model pairs separated by commas: venom-default=gpt-5.4-mini,venom-fast=gpt-5.4-nano. The model name on the wire is the mapped one. |
unset: venom maps the aliases itself from the endpoint's model list when it can, and says so |
VENOM_MAX_TOKENS_FIELD |
Which request field carries the output cap: max_tokens or max_completion_tokens. Any other value is ignored. |
max_completion_tokens (api.openai.com: the SDK's own choice) |
VENOM_THINKING |
Default thinking level per model, as model=level pairs: venom-fast=off,venom-default=low. Levels: off, minimal, low, medium, high, xhigh. |
the model's default |
VENOM_PROJECT |
The project venom's requests are charged to on Venom Cloud, sent as x-venom-project. Never part of a prompt. |
the key's own project |
VENOM_NETWORKS |
Networks this machine can reach, as tailnet:<name>,lan:<label>, sent as x-venom-networks so Venom Cloud can send requests straight to a daemon on those networks. |
unset: requests are relayed |
VENOM_ORCH_URL |
The orchestrator venom models manages. |
VENOM_BASE_URL without /v1 when it is local, else http://127.0.0.1:8787 |
VENOM_CLOUD_URL |
A Venom Cloud deployment, used with VENOM_CLOUD_KEY (a Cloud client key). Wins over the login venom cloud login saved. Neither set: no Cloud traffic. |
unset |
Directories and state
| Variable | What it does | Default |
|---|---|---|
VENOM_HOME |
venom's state directory: permissions, settings, caches, keys. | ~/.venom |
VENOM_CODING_AGENT_DIR |
The agent config directory venom hands to pi (settings, sessions). venom sets it from VENOM_HOME when only that is set. |
~/.venom/agent |
VENOM_CODING_AGENT_SESSION_DIR |
Where sessions are kept. --session-dir <dir> does the same per run. |
<agent dir>/sessions |
VENOM_TOOL_DIRS |
Directories searched for language servers and formatters before PATH, PATH-style. Only absolute paths count. |
unset |
VENOM_KEYSTORE |
Where venom keeps the keys it creates (browser profiles, the signed action log): keychain, secret-service or file. |
the macOS keychain on a Mac, the Secret Service where secret-tool is installed, else a 0600 key file |
VENOM_EVALS_DIR |
The evals checkout venom eval runs from. |
the nearest evals/ above the current directory |
NODE_COMPILE_CACHE |
Node's compile cache. When set, the harness also makes this directory read-only inside the sandbox, like $VENOM_HOME/cache. |
Node's default |
RIPGREP_CONFIG_PATH |
A ripgrep config file. When set, venom's grep narrowing steps aside, since the config could change what ripgrep matches. | unset |
Behaviour and terminal
| Variable | What it does | Default |
|---|---|---|
VENOM_DEBUG |
1 prints harness diagnostics, hook messages and compaction steps, and the warnings venom normally hides. |
off |
VENOM_MAX_WIDTH |
Chat width on wide terminals: a number of columns (clamped to 40 to 1000), auto or full (no cap). Beats the width saved with /width. |
auto (100 columns) |
VENOM_SOUND_PLAYER |
A player command of your own for event sounds; the sound file is appended. Example: mpv --no-video. |
the system player |
VENOM_OFFLINE |
1 registers MCP servers disabled and turns off web_fetch and web_search. |
off |
VENOM_ONLINE |
1 lets pi make its own startup network calls (model catalog refresh, update check). venom never sends crash reports, even with it. |
off |
PI_OFFLINE |
pi's switch for those startup calls. venom sets PI_OFFLINE=1 unless VENOM_ONLINE=1 or you set it yourself; venom doctor reports which is in effect. |
1 (set by venom) |
PI_PACKAGE_DIR |
Where pi reads its branding. The release build sets it so pi uses venom's name and ~/.venom. venom doctor warns about a stale value. |
set by the launcher |
VENOM_NODE |
The node binary the release launcher runs venom with. |
the Node runtime shipped in the release |
VENOM_AUTHOR |
The author name written into auto-memory files. | git user.name, else the OS user |
VENOM_AGENT |
The name venom intent claim records as the claimer. |
the OS user |
VENOM_OWNER |
Your handle for venom inbox --mine; several separated by commas. |
unset (--mine asks you to set it) |
VENOM_DEV_URL |
The dev server venom browser resolves a bare route such as /settings against. --base does the same per run. |
unset |
VENOM_TRACE_PROVIDER_STREAM |
1 records each session's raw provider stream to <session>.stream.jsonl, which venom export --format jsonl includes. |
off |
VENOM_LSP_UNSANDBOXED_FOR_MEASUREMENT |
1 runs language servers outside the sandbox. It exists to measure the sandbox's cost in evals; do not use it otherwise. |
off |
VENOM_LEASE_WAIT_MS |
How long an edit waits for a file lease another agent holds, in milliseconds. | 30000 |
VENOM_CLI_FLAGS |
Flags make cli passes to every run, before ARGS. Only make cli reads it. |
unset |
Permissions and auto mode
| Variable | What it does | Default |
|---|---|---|
VENOM_AUTO_TIMEOUT_MS |
Time limit for one auto-mode review, in milliseconds. Same as permissions.auto.timeout_ms. |
no limit beyond the request's own |
VENOM_AUTO_ON_FAILURE |
What auto mode does when its reviewer fails or times out: deny, or anything else for ask. Same as permissions.auto.on_failure. |
ask |
VENOM_POLICY_FILE |
An organisation policy file, used only where /etc/venom/policy.json does not exist. |
unset |
VENOM_SERVER_TOKEN |
The bearer token venom serve requires, 16 characters or more. |
unset (venom serve refuses to start) |
venom keeps its own control-plane credentials away from anything the agent runs. The list is VENOM_INTERNAL_ENV in @venom/harness/permissions: VENOM_SERVER_TOKEN and VENOM_ADMIN_TOKEN. When venom starts with either set, it re-executes itself once without them and reads them back from a 0600 file in a private temp directory, named by VENOM_ENV_HANDOFF; then it removes them from its environment, so bash, hooks, MCP servers and language servers never inherit them. VENOM_ENV_HANDOFF is set by venom for that one step; do not set it yourself.
VENOM_EXEC_CMD is also internal: the harness passes a sandboxed command through it so the command is never re-quoted.
Web search
The web_search tool asks the orchestrator's POST /v1/search when one is configured. Without one, the CLI searches directly in this order: SearxNG, Brave, Tavily, then DuckDuckGo (no key).
| Variable | What it does | Default |
|---|---|---|
VENOM_SEARCH_URL |
Your SearxNG, tried first, for example http://127.0.0.1:8888. |
unset |
BRAVE_API_KEY |
Brave Search API key. search.brave_key_env in venom.yaml can name another variable. |
unset (skipped) |
TAVILY_API_KEY |
Tavily API key. search.tavily_key_env can name another variable. |
unset (skipped) |
EXA_API_KEY |
Exa API key, used by the orchestrator's search chain only. | unset (skipped) |
SEARXNG_PORT |
Host port of the compose SearxNG (--profile search). |
8888 |
SEARXNG_SECRET |
SearxNG's secret key in compose. Set your own if the instance is reachable by anyone else. | venom-local-searxng-secret |
Tracing
Off unless an endpoint is set. Spans go to your own collector, never anywhere else.
| Variable | What it does | Default |
|---|---|---|
OTEL_EXPORTER_OTLP_ENDPOINT |
Your OTLP collector, for example http://127.0.0.1:4318. Read by the orchestrator and, when exported in its shell, the CLI. |
unset (no tracing) |
OTEL_EXPORTER_OTLP_HEADERS |
Headers for the collector, such as Authorization=Basic%20…. |
unset |
OTEL_EXPORTER_OTLP_PROTOCOL |
The OTLP protocol. | http/protobuf |
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT |
true puts prompt and response text in the CLI's spans. |
off (no content) |
Dev stack (compose and make)
These are read by docker-compose.yml, the Makefile and its scripts, from .env.
| Variable | What it does | Default |
|---|---|---|
VENOM_PORT |
Host port of the orchestrator container, always on 127.0.0.1. | 8787 |
WEB_PORT |
Host port of the web console container. | 3000 |
WEB_BIND |
Host address the console port binds to. 0.0.0.0 exposes it beyond this machine. |
127.0.0.1 |
VENOM_LOCAL_BACKEND |
The compose service that serves the local model, ollama or vllm; make up starts it too. Empty for a native Ollama. Written by make model. |
unset |
PROMETHEUS_RETENTION |
How long the compose Prometheus keeps data (--profile observability). |
15d |
GRAFANA_ADMIN_PASSWORD |
The compose Grafana's admin password. | admin |
CLOUD_DB_PORT |
Host port of the local Venom Cloud Postgres (make cloud-dev). |
5433 |
CLOUD_DB_PASSWORD |
Its password. | venom-local-db |
CLOUD_PORT |
Port of the local Venom Cloud (next dev). |
3100 |
Local inference
| Variable | What it does | Default |
|---|---|---|
OLLAMA_KEEP_ALIVE |
How long the compose Ollama keeps a model loaded; -1 keeps it forever. |
30m |
OLLAMA_NUM_PARALLEL |
Parallel slots per model. KV memory grows with this times the context length; use 1 on a 16 GB machine. |
2 |
OLLAMA_MAX_LOADED_MODELS |
How many models stay resident. | 2 |
VLLM_TOOL_PARSER |
vLLM's tool-call parser. Must match the model family (qwen3_coder, openai, mistral, hermes, ...). |
qwen3_coder |
VLLM_EXTRA_ARGS |
Extra vLLM arguments, for example --reasoning-parser qwen3. |
unset |
VLLM_GPU_UTIL |
The share of GPU memory vLLM may use. | 0.90 |
VLLM_KV_OFFLOAD_GB |
Host RAM in GB for offloaded prefix-cache blocks. | unset (off) |
VLLM_SPEC_CONFIG |
Speculative decoding config as JSON, for example {"model":"Qwen/Qwen3-0.6B","num_speculative_tokens":5}. make model sets it when a preset's draft model fits. |
unset (off) |
LLAMACPP_HF |
The GGUF the compose llama.cpp serves, as repo:quant, pulled from Hugging Face on first start. |
Qwen/Qwen3-8B-GGUF:Q4_K_M |
LLAMACPP_HF_DRAFT |
A draft GGUF for speculative decoding; same tokenizer. | unset (off) |
LLAMACPP_CTX |
llama.cpp's total context, split across its slots (LLAMACPP_SLOTS, default 2). |
65536 |
HF_TOKEN |
Hugging Face token, only for gated repositories. | unset |
OLLAMA_BASE_URL, OLLAMA_CONTEXT_LENGTH, VLLM_BASE_URL, VLLM_MODEL and VLLM_MAX_MODEL_LEN configure the orchestrator's local upstreams and are listed in the orchestrator section.
Board and gate
Read by the board and merge-queue views (venom board, the console's board page).
| Variable | What it does | Default |
|---|---|---|
BOARD_REPO |
The GitHub repository the board reads, as owner/name. --repo does the same. |
the origin remote |
BOARD_STATE |
The board's state directory, with one <issue>.pid file per running worker. |
~/.venom/board |
GATE_FLAKY_LEDGER |
The gate's flaky-test ledger, a TSV file. | ~/.venom/gate-history.tsv |
GATE_QUEUE_STATE |
The state file the gate's batch queue writes. | $TMPDIR/venom-gate-queue.json |
Set by venom
| Variable | Meaning |
|---|---|
VENOM_CLI_VERSION |
The running CLI's version, set at start so libraries and plugins can read it (plugin minVenom checks use it). |
VENOM_ENV_HANDOFF |
The credential hand-over file during the one re-exec described above. |
VENOM_EXEC_CMD |
The command line inside a sandboxed exec. |
Troubleshooting
- A variable seems ignored.
venom doctorprints the resolved endpoint, model, alias map and agent directory with the source of each value. A flag beats the variable, and the variable beatsvenom.yaml. - An empty value in
.envdoes nothing. That is by design: empty counts as unset. - The agent cannot see
VENOM_SERVER_TOKENin a shell command. Also by design; see Permissions and auto mode.