---
title: Environment variables
description: Every environment variable the venom CLI, the harness and the dev stack read, with what it does and its default.
section: reference
order: 10
audience: [user, operator, builder, agent]
sources: [.env.example, cli/src/branding.ts, cli/src/setup.ts, cli/src/own-env.ts, packages/harness/src/provider/index.ts, packages/harness/src/subagents/tiers.ts, docker-compose.yml, Makefile]
features: [reference.env]
---

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](/docs/orchestrator.md); 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:

```bash
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 {#endpoint}

| 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 {#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 {#behaviour}

| 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 {#permissions}

| 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 {#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 {#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) {#dev-stack}

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 {#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](/docs/orchestrator.md).

### Board and gate {#board}

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 {#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 {#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](#permissions).

## Related

- [Architecture, ports and contracts](/docs/reference/architecture.md)
- [Limits and defaults](/docs/reference/limits.md)
- [venom CLI quickstart](/docs/getting-started/cli-quickstart.md)
