Skip to content
Docs menu

Environment variables

Every environment variable the venom CLI, the harness and the dev stack read, with what it does and its default.

View .md

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 where

venom --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.

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 doctor prints the resolved endpoint, model, alias map and agent directory with the source of each value. A flag beats the variable, and the variable beats venom.yaml.
  • An empty value in .env does nothing. That is by design: empty counts as unset.
  • The agent cannot see VENOM_SERVER_TOKEN in a shell command. Also by design; see Permissions and auto mode.