Models, offline mode and tool billing
Choose the main, delegation, vision and decision models and their thinking levels, point venom at an orchestrator, and configure offline mode, tool billing, tests after edits and learned skills.
venom speaks the OpenAI API to one endpoint, normally a venom orchestrator or Venom Cloud, and asks it for models by alias. These keys pick which aliases or model ids it asks for. A gear sets the same things as a switchable preset; the keys here are the defaults with no gear engaged.
orchestrator:
base_url: http://localhost:8787/v1
model: venom-default
tiers:
fast: venom-fast
smart: venom-smart
thinking:
venom-default: medium
venom-fast: off
vision_model: venom-vision
decision_model: venom-decide
agents:
explorer: { model: qwen-fast }Where models are served
| Key | Env var | Default | Meaning |
|---|---|---|---|
orchestrator.base_url |
VENOM_BASE_URL |
http://localhost:8787/v1 |
the OpenAI-compatible endpoint, including /v1 |
The key for that endpoint comes only from VENOM_API_KEY, never from a file. A project file's orchestrator block needs the project to be trusted, because it decides where your prompts go, and an organisation policy that pins the endpoint wins over it. Any OpenAI-compatible server works (Ollama, vLLM, llama.cpp, a provider); without a venom orchestrator, VENOM_ALIAS_MAP maps the venom-* aliases to real ids (venom-default=qwen3:8b,venom-fast=qwen3:4b), and venom maps them automatically when the server lists no venom-* ids.
The main model
| Key | Env var | Default |
|---|---|---|
model |
VENOM_MODEL |
venom-default (the orchestrator's default alias) |
--model <id> beats VENOM_MODEL, which beats model:. /model switches during a session. A model you chose with --model, VENOM_MODEL or /model is never switched silently by offline mode or stuck detection.
Delegation tiers and per-agent models
| Key | Env var | Default | Used by |
|---|---|---|---|
tiers.fast |
VENOM_FAST_MODEL |
venom-fast |
the explorer, compaction summaries, agents with model: fast |
tiers.smart |
VENOM_SMART_MODEL |
venom-smart |
agents with model: smart |
agents.<name>.model |
the agent file's model: |
one named agent (explorer, worker, verifier, or your own) |
tiers is the delegation layer: the main model hands searches, reads and test runs to subagents on these models. A task call that names its own model still wins over agents:.
Thinking levels
| Key | Env var | Default |
|---|---|---|
thinking.<model> |
VENOM_THINKING |
venom-fast: off, venom-default: medium |
Levels are off, minimal, low, medium, high and xhigh, sent as reasoning_effort to models that take it. Keys are model ids or aliases. VENOM_THINKING takes the same map as text (venom-fast=off,venom-default=low); it is merged with the file's map and wins per model. A gear's thinking applies to its main model while engaged.
Vision and decision models
| Key | Env var | Default | Meaning |
|---|---|---|---|
vision_model |
VENOM_VISION_MODEL |
venom-vision |
describes pasted or read images in text for a main model that takes no images |
decision_model |
VENOM_DECISION_MODEL |
venom-decide |
the small model auto mode's decider asks before the LLM classifier, and that search.rerank: on uses |
Decisions are advisory: the decision model never has the final say on a permission. Under a route profile that doesn't serve venom-decide (gear china), the decider is skipped and the classifier decides.
Offline mode
Two separate things share the name.
Offline flag. --offline (or VENOM_OFFLINE=1) starts a session that registers remote MCP servers disabled and has no web_fetch or web_search tools. Point the model endpoint at a local orchestrator for a session with no network at all.
VENOM_BASE_URL=http://localhost:8787/v1 venom --offlineAutomatic switch. When a run fails because the network is gone (the orchestrator reports its cloud upstream down, or the machine has no network link), venom switches the session to the local gear (gear 4, local, on Ollama) with one notice and continues there. It reads only what the session already has; no probe goes out. When the upstream answers again, one line offers the way back; venom never switches back on its own, because a switch breaks the prompt cache.
| Key | Type | Default | Meaning |
|---|---|---|---|
offline.auto |
boolean | true |
switch on its own; false only says so and offers /offline local |
offline.gear |
gear name | local |
the gear to switch to |
| Command | Does |
|---|---|
/offline |
the state: online, or offline since when and what it watches |
/offline local |
switch to the offline gear now |
/offline back |
return to the gear (or model) you had before |
A model you chose yourself is never moved silently: the TUI asks first. With VENOM_BASE_URL on a remote server (Venom Cloud or another machine), a lost connection gets one notice and no switch, since the local gear would go through the same server; run an orchestrator on this machine for offline work.
Tool billing
Some tools cost money: a paid search API, a metered MCP server. tool_billing: declares the price per tool name (an MCP tool as pi names it, such as mcp__search__query; a plugin or app tool by its name). Built-in tools are free, and venom looks no prices up.
tool_billing:
mcp__search__query:
unit: input.num_results
block: 10
usd: 0.01
vendor_usd: result.usage.cost_usd
mcp__ocr__page:
per: call
usd: 0.002
mcp__crawl__run:
parts:
- { per: call, usd: 0.001 }
- { unit: result.pages, block: 1, usd: 0.0005 }| Key | Type | Default | Meaning |
|---|---|---|---|
tool_billing.*.per |
free | call | unit |
unit when unit is set, else call |
what is billed |
tool_billing.*.usd |
number | USD per call, or per block of units | |
tool_billing.*.unit |
input.<path> | result.<path> |
where the unit count is read (a number, or an array's length) | |
tool_billing.*.block |
integer | 1 |
units per billed block (10 bills 11 units twice) |
tool_billing.*.assume |
number | 1 for the estimate, 0 when settling | units assumed when the path is absent |
tool_billing.*.parts |
list of entries | a composite: these entries are added | |
tool_billing.*.vendor_usd |
result.<path> |
the vendor's own USD meter in the result; it wins over the estimate |
venom estimates before the call and settles from the result after it; a difference from the vendor meter is kept as a mismatch. Tool spend shows apart from model spend: a "Tool spend" line in /cost, tools $… in the turn footer, and role tool in venom cost --by role. A bad entry is ignored and the tool stays free; pricing never blocks a call. Apps on the harness pass the same map as HarnessOptions.toolBilling.
Tests after edits
After an edit batch, venom runs only the tests the change can affect, in the background, and tells the model about failures at its next turn. The same results feed the flaky-test detector (venom flaky).
| Key | Type | Default | Meaning |
|---|---|---|---|
tests.on_edit |
auto | off |
auto |
run affected tests after each edit batch, when the permission rules allow the command (or you allow it once) |
tests.max_seconds |
integer | 60 |
time cap for one background run, all suites together |
tests.flaky_after |
integer | 3 |
times a test may fail then pass with no code change before venom proposes filing an issue. It never files one itself |
Learned skills
| Key | Type | Default |
|---|---|---|
learn |
boolean | true |
After you do the same kind of job three times, venom drafts a template or skill from your session summaries with one cheap request (at most one a day) and says so in one line. Nothing is saved or shared until you accept it in /template learn. learn: false never drafts.
Model catalog
The orchestrator can serve a vetted model catalog (context windows, prices) in pi's shard format at GET /api/models/providers/<id>, from config/model-catalog/ or the directory in VENOM_MODEL_CATALOG (an orchestrator variable). The CLI does not fetch a catalog yet, so there is no venom.yaml key for it.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
model not found on the first turn |
The endpoint doesn't serve the alias. List what it serves with venom doctor, then set model: or VENOM_ALIAS_MAP |
orchestrator.base_url ignored |
It comes from an untrusted project file, or the organisation policy pins another endpoint. venom config shows the warning |
| Images are ignored by a text-only model | vision_model is not served; point it at a served vision model |
| Offline mode didn't switch | The local gear isn't available (Ollama not running), the model was chosen by hand, or VENOM_BASE_URL is remote |
Related
- Gears: presets of these settings, switched in one key.
- Environment variables.
- venom CLI quickstart.