---
title: Models, offline mode and tool billing
description: 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.
section: configuration
order: 40
audience: [user, operator, builder]
sources: [packages/harness/src/config/index.ts, packages/harness/src/config/schema.ts, packages/harness/src/guards/overthink.ts, cli/src/gears.ts, cli/src/setup.ts, cli/src/branding.ts, docs/configuration.md, docs/test-watch.md]
features: [configuration.model, configuration.tiers, configuration.thinking, configuration.vision-model, configuration.decision-model, configuration.orchestrator, configuration.offline, configuration.tool-billing, configuration.tests, configuration.learn]
---

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](/docs/configuration/gears.md) sets the same things as a switchable preset; the keys here are the defaults with no gear engaged.

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

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

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

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

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

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.

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

```yaml
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 {#tests}

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

| 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 {#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](/docs/configuration/gears.md): presets of these settings, switched in one key.
- [Environment variables](/docs/configuration/env-vars.md).
- [venom CLI quickstart](/docs/getting-started/cli-quickstart.md#model).
