Skip to content
Docs menu

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.

View .md

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 --offline

Automatic 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