---
title: Orchestrator environment variables
description: Every environment variable the orchestrator, its shipped config, the desktop daemon and the public-mesh auditor read, with defaults.
section: orchestrator
order: 50
audience: [operator, agent]
sources: [docs/architecture.md, .env.example, config/orchestrator.yaml, services/go-orchestrator/cmd/orchestrator/main.go, services/go-orchestrator/internal/mesh/config.go, services/go-orchestrator/cmd/venom-auditor/main.go, services/go-orchestrator/internal/localmodels/vllmrun.go]
features: [orchestrator.env]
---

Secrets go in the environment (a gitignored `.env` in a checkout, your secret store in production), never in `orchestrator.yaml`: the config names a variable (`api_key_env: OPENAI_API_KEY`) and the orchestrator reads it at load. Keys are never logged or returned by the admin API.

The shipped config refers to variables with `${VAR}` or `${VAR:-default}`; you can use the same syntax for any value in your own file.

## Process {#process}

| Variable | Default | What it does |
|---|---|---|
| `VENOM_CONFIG` | `config/orchestrator.yaml` | The config file. |
| `VENOM_PRICES` | `prices.yaml` next to the config | The price table. Missing: every cost is $0, with a warning. |
| `VENOM_MODEL_CATALOG` | `model-catalog/` next to the config | Directory of model-catalog shards served at `GET /api/models/providers/{id}`. |
| `VENOM_DATA_DIR` | `./data` | SQLite database (keys, request log, spend ledger, batches, files) and state files. |
| `VENOM_LISTEN` | `127.0.0.1:8787` | Listen address, read by the shipped config's `listen:`. |
| `VENOM_API_KEY` | none | The bootstrap client key accepted on `/v1/*`. More keys come from `POST /admin/v1/keys`. |
| `VENOM_ADMIN_TOKEN` | none | Bearer token for `/admin/v1/*`; unset, the admin API answers `503`. |
| `VENOM_ALLOW_OPEN` | unset | `1` lets the orchestrator run with no client key on a non-loopback address. Without it that combination refuses to start. |
| `LOG_LEVEL` | `info` | `debug`, `info`, `warn` or `error`. |
| `LOG_JSON` | unset | `1` for JSON logs. |
| `VENOM_CASSETTE_MODE` | `off` | `record` writes every complete `200` to a cassette; `replay` answers from cassettes and never calls an upstream ([Operations](/docs/orchestrator/operations.md#cassettes)). |
| `VENOM_CASSETTE_DIR` | `$VENOM_DATA_DIR/cassettes` | Where cassettes live. |
| `VENOM_ORCH_URL` | `http://localhost:8787` | Not read by the orchestrator: where the web console, the eval runner and backtest scripts reach its admin API. |
| `OTEL_EXPORTER_OTLP_ENDPOINT`, `OTEL_EXPORTER_OTLP_HEADERS`, `OTEL_EXPORTER_OTLP_PROTOCOL` | unset (off) | OpenTelemetry trace export over OTLP/HTTP. Spans never carry prompt or reply content. |

## Providers in the shipped config {#providers}

Every cloud upstream is disabled while its key variable is empty, so nothing calls that provider.

| Variable | Default | What it does |
|---|---|---|
| `OPENAI_API_KEY` | none | The `openai` upstream. |
| `ANTHROPIC_API_KEY` | none | The commented-out `anthropic` upstream. |
| `ZAI_API_KEY` | none | The `zai` upstream (aliases `glm`, `glm-fast`, `glm-vision`, a `venom-fast` fallback). |
| `ZAI_BASE_URL` | `https://api.z.ai/api/paas/v4` | `https://api.z.ai/api/coding/paas/v4` for the GLM Coding Plan. |
| `QWEN_API_KEY` | none | The `qwen` upstream (kind `dashscope`: aliases `qwen`, `qwen-fast`, `qwen-coder`, `qwen-vision`, `deepseek`, `kimi`, and `glm`'s first target). |
| `QWEN_BASE_URL` | `https://dashscope-intl.aliyuncs.com/compatible-mode/v1` | Another Model Studio region's endpoint (a key from that region). |
| `MISTRAL_API_KEY`, `MISTRAL_BASE_URL` | none, `https://api.mistral.ai/v1` | The commented-out `mistral` upstream. |
| `MINIMAX_API_KEY`, `MINIMAX_BASE_URL` | none, `https://api.minimax.io/v1` | The commented-out `minimax` upstream; `https://api.minimaxi.com/v1` for mainland China. |
| `TYPESAFE_API_KEY` | none | The `typesafe` decision upstream (alias `venom-decide`); unset, the alias is not listed. |
| `TYPESAFE_BASE_URL` | `https://api.typesafe.ai/v1` | Its endpoint. |
| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`, `AWS_REGION` | none | IAM credentials and region for `bedrock` and `sagemaker` upstreams; each upstream's `aws:` block can name other variables. |
| `SEARXNG_URL` | empty (skipped) | The SearxNG instance `POST /v1/search` asks first. |
| `BRAVE_API_KEY`, `TAVILY_API_KEY`, `EXA_API_KEY` | none | Search backends in `/v1/search`'s chain; each is skipped without its key. |

## Local engines {#local}

| Variable | Default | What it does |
|---|---|---|
| `OLLAMA_BASE_URL` | `http://localhost:11434/v1` | The `ollama` upstream (`make up` points it at the container or a host Ollama). |
| `OLLAMA_CONTEXT_LENGTH` | `32768` | The context window declared for Ollama models (Ollama truncates silently past its own setting, so keep them equal). |
| `VENOM_OLLAMA_MODEL` | `qwen3:8b` | The Ollama model behind `venom-default` and `venom-smart`'s local target. |
| `VENOM_OLLAMA_FAST_MODEL` | `qwen3:4b` | The Ollama model behind `venom-fast`. |
| `VENOM_OLLAMA_EMBED_MODEL` | `qwen3-embedding:0.6b` | The only target of `venom-embed`. |
| `VENOM_OLLAMA_VISION_MODEL` | `qwen2.5vl:7b` | `venom-vision`'s last (local) target. |
| `VLLM_BASE_URL` | `http://localhost:8000/v1` | The `vllm` upstream. |
| `VLLM_MODEL` | `Qwen/Qwen3-Coder-30B-A3B-Instruct` | The model vLLM serves, first target of `venom-default`, `venom-fast` and `venom-smart`. |
| `VLLM_MAX_MODEL_LEN` | `0` (discovered) | vLLM's context window when you want to pin it. |
| `VENOM_LLMFIT_URL`, `VENOM_LLMFIT_BIN` | none, then `llmfit` on `PATH` | Where `/admin/v1/local` reads hardware and fit estimates: an `llmfit serve`, else the binary. |
| `VENOM_DOCKER_BIN` | `docker` on `PATH` | The Docker CLI the one-click vLLM (`POST /admin/v1/local/serve`) runs. |
| `VENOM_VLLM_IMAGE` | `vllm/vllm-openai:v0.31.0` | The image it starts. |

## Computers {#computers}

Venom Computers gives each agent a persistent browser on this machine ([how it works](/docs/deploy/computers.md)). Off unless `VENOM_COMPUTERS=on`, and only with Docker on the `PATH` and an orchestrator that is not itself in a container.

| Variable | Default | What it does |
|---|---|---|
| `VENOM_COMPUTERS` | off | `on` turns it on. |
| `VENOM_SOURCE_DIR` | the working directory or the executable's, or a parent | The repo checkout that holds `deploy/computer/Dockerfile`, so one-click [Enable Computers](/docs/computers/enable.md) can build the image when the published one is not available. |
| `VENOM_COMPUTERS_IMAGE` | `venom-computer:dev` | The host image. Unset: the digest linked into a release build, else the local build (`make computer-image`). Wins over both. See [Run Computers on your own daemon](/docs/computers/self-host.md#image). |
| `VENOM_COMPUTERS_MEMORY` | half the machine's RAM | The RAM active seats may use (`8g`, `512m`). `max_active` is the lower of `VENOM_COMPUTERS_MAX_ACTIVE` and this divided by the memory per active seat. |
| `VENOM_COMPUTERS_MAX_ACTIVE` | `0` (the RAM budget alone) | A cap on seats with a running browser. |
| `VENOM_COMPUTERS_MAX_SEATS` | `100` | Seats this daemon provisions (profiles on disk). |
| `VENOM_COMPUTERS_SEATS_PER_HOST` | `25` | Seats per host container. A private seat gets a host of its own. |
| `VENOM_COMPUTERS_QUEUE_MAX` | `200` | Starts that may wait for a slot before the next one is refused with `429`. |
| `VENOM_COMPUTERS_IDLE_AFTER` | `10m` | Quiet time (no tool call, nobody watching) before a seat hibernates. |
| `VENOM_COMPUTERS_MEM_PER_SEAT_MIB` | `450` | The starting estimate of memory per active browser seat; it follows what the hosts report. |
| `VENOM_COMPUTERS_DESKTOP_MEM_PER_SEAT_MIB` | `500` | The same for a desktop seat (an X display, a window manager, a headful browser and its apps). |
| `VENOM_COMPUTERS_HOST_MEMORY`, `VENOM_COMPUTERS_HOST_CPUS` | RAM budget capped at 16 GiB, `4` | The `--memory` and `--cpus` of each host container. |
| `VENOM_COMPUTERS_PROXY` | none | The `--proxy-server` for every seat's Chromium (the guard/egress proxy). |
| `VENOM_COMPUTERS_SERVE_BIN` | the desktop daemon's `bin/venom`, else `venom` | The binary run as `venom serve` for a seat's agent sessions. |

A model chosen with `POST /admin/v1/local/select` sets `VENOM_OLLAMA_MODEL` or `VENOM_OLLAMA_FAST_MODEL` in the running process and is kept in `$VENOM_DATA_DIR/local-models.json`.

## Mesh mode {#mesh}

Mesh mode connects the orchestrator to Venom Cloud as a daemon. It only dials out, and none of these is read unless `VENOM_CLOUD_URL` is set (or the dashboard connects with `POST /admin/v1/mesh/connect`).

| Variable | Default | What it does |
|---|---|---|
| `VENOM_CLOUD_URL` | unset (mesh off) | The cloud to join, with the credential `orchestrator mesh join <url> <vjt_…>` wrote to `$VENOM_DATA_DIR/mesh/`. |
| `VENOM_MESH_JOIN_TOKEN` | none | A `vjt_…` join token used at start when no credential exists yet (containers). Never written to disk. |
| `VENOM_MESH_NAME` | the host name | The daemon's name in the cloud console. |
| `VENOM_MESH_ENDPOINTS` | none (relay only) | Reachable endpoints, `kind=url[,network]` separated by `;`, for direct connections. |
| `VENOM_MESH_GEO` | inferred from the time zone | The daemon's location; `none` reports none. |
| `VENOM_MESH_ACCEPT_TEAMS` | empty (no allowlist) | Comma-separated team allowlist: jobs from other teams are refused. |
| `VENOM_MESH_MAX_JOBS` | the sum of the upstreams' `max_inflight` | Concurrent cloud jobs (a positive integer). |
| `VENOM_MESH_GPUS` | none | GPUs reported in the daemon's capabilities, e.g. `RTX 4090:24`. |
| `VENOM_MESH_SERVE_URL` | none | Forward remote `venom serve` sessions to the `venom serve` at that URL (needs `VENOM_SERVER_TOKEN`). |
| `VENOM_MESH_SERVE_FILE` | none | A JSON file whose `serve_url` names the local `venom serve`, re-read while the orchestrator runs, so serve can start, stop or move without a restart; no `serve_url`, no serve. Needs `VENOM_SERVER_TOKEN`; `VENOM_MESH_SERVE_URL` wins. The desktop daemon points it at its `run.json` ([Projects](/docs/deploy/projects.md)). |

A malformed `VENOM_MESH_*` value stops the start; a failed join or a revoked credential leaves mesh off and the local `/v1` serving. The protocol is covered with Venom Cloud and the mesh.

## Desktop daemon {#daemon}

Set by the `venom-daemon` launcher; you rarely set them yourself.

| Variable | Default | What it does |
|---|---|---|
| `VENOM_DAEMON_LAUNCHER` | none | The launcher's path; turns on start at login in `/admin/v1/daemon`. |
| `VENOM_DAEMON_HOME` | the install root | Where the daemon's binaries live. |
| `VENOM_DAEMON_DIR` | `~/.venom/daemon` (`%LOCALAPPDATA%\Venom` on Windows) | The daemon's state directory. |
| `VENOM_DAEMON_NODE` | the bundled Node.js | The Node binary the launcher runs the console with. |
| `VENOM_DAEMON_UPDATE_URL` | `https://github.com/elishahbiz/venom-releases/releases` | Releases base URL for the opt-in auto-update (a mirror works). |
| `VENOM_DAEMON_UPDATE_IDLE`, `VENOM_DAEMON_UPDATE_MAX_WAIT` | `30s`, `30m` | The idle window an update waits for, and its cap. |

## Public-mesh auditor {#auditor}

`venom-auditor` (a separate binary run by the public mesh's operators) replays sampled public jobs on reference vLLMs and sends canaries. It needs `VENOM_CLOUD_URL` and its auditor token.

| Variable | Default | What it does |
|---|---|---|
| `VENOM_AUDITOR_REFERENCES` | required for audits | Comma-separated `[id=]url[#model]` reference vLLMs; the second runs confirmation reruns. |
| `VENOM_AUDITOR_LISTEN` | `127.0.0.1:9797` | Its `/health` and `/metrics`; `off` for none. |
| `VENOM_AUDITOR_CORPUS` | none | A directory of `task.json` prompts and source files for canaries. |
| `VENOM_AUDITOR_CONCURRENCY` | `2` | Audits replayed at once. |
| `VENOM_AUDITOR_POLL` | `10s` | Wait when no audit is pending. |

## Related

- [Configuration reference](/docs/orchestrator/configuration.md), [Upstreams and kinds](/docs/orchestrator/upstreams.md), [Operations](/docs/orchestrator/operations.md).
