---
title: Environment variables
description: The VENOM_* environment variables the CLI reads, what each sets, its default, and the venom.yaml key it overrides.
section: configuration
order: 50
audience: [user, operator, builder, agent]
sources: [cli/src/branding.ts, packages/harness/src/config/index.ts, cli/src/setup.ts, cli/src/venom-config.ts, docs/configuration.md, docs/architecture.md]
features: []
---

Environment variables sit between flags and config files in [precedence](/docs/configuration.md#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.

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

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

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](/docs/orchestrator/environment.md) documents the rest of its variables.

## Related

- [Configuration](/docs/configuration.md): files, precedence and trust.
- [venom.yaml reference](/docs/configuration/venom-yaml.md).
