---
title: Glossary
description: Short definitions of the words venom's docs, config and APIs use, from alias and gear to daemon, relay and lease.
section: reference
order: 60
audience: [user, operator, builder, agent]
sources: [docs/architecture.md, docs/configuration.md, docs/cloud-mesh.md, config/orchestrator.yaml]
features: []
---

Terms are grouped by where you meet them. Within a group they are alphabetical.

## Models and routing {#routing}

| Term | Meaning |
|---|---|
| Affinity | Keeping a session on the upstream that served it before, so the engine's prompt (KV) cache is reused. Driven by `x-venom-session`. |
| Alias | A model name the orchestrator routes, such as `venom-default` or `venom-fast`, instead of a concrete model id. Defined by a route. |
| Auto routing | The `venom-auto` alias: rules pick a `cheap`, `balanced` or `premium` tier per request and say why in `x-venom-auto-*` headers. |
| Batch request | A request sent with `x-venom-urgency: batch`: it waits for a provider batch window at a lower price and answers `202` with a `Location`. |
| Circuit breaker | Per-target state that stops sending traffic to a target after repeated failures, then probes it again after a cooldown. |
| Experiment | A route whose traffic is split between variants by weight; each answer names its variant in `x-venom-variant`. |
| Fallback | Trying the route's next target when one fails before the first byte. `x-venom-fallback` says why. |
| Gear | A named set of model choices, one per role, that you switch between in the CLI (`/gear`). A gear can also name a route profile and a provider tier. Defined in the orchestrator config, `venom.yaml`, or by an organisation on Venom Cloud. |
| Kind | The wire format of an upstream (`openai`, `vllm`, `ollama`, `anthropic`, `bedrock`, `mistral`, `minimax`, ...). The orchestrator picks an adapter by kind. |
| Role | A job inside a session that a gear assigns a model to: `main`, `workers`, `smart`, `vision`, `summary`, `classifier`, `reflex`, `browser`. |
| Route | The mapping from an alias to its targets and the strategy that picks among them. |
| Route profile | A named policy (`x-venom-profile`) that limits which targets a request may use and adds body defaults, such as a reasoning effort or an output cap. |
| Service tier | A provider's price and latency class: `default`, `flex`, `priority`, `batch`. Asked for with `x-venom-service-tier`. |
| Shadow | Replaying a sample of a route's traffic to a candidate model, under a daily spend cap, to compare it without serving its answers. |
| Side request | A request a session makes besides its main turns: the auto-mode reviewer, a prompt hook, an image description, a summary. Sent as `x-venom-session: <session>:<kind>`. |
| Target | One upstream and model inside a route. |
| Tier | In the harness: the `fast` and `smart` models subagents can ask for (`VENOM_FAST_MODEL`, `VENOM_SMART_MODEL`). In auto routing: `cheap`, `balanced`, `premium`. |
| Upstream | One inference backend the orchestrator calls: a URL, a kind, a key and its models. |

## Agent sessions {#sessions}

| Term | Meaning |
|---|---|
| Auto mode | A permission mode in which a model reviews each call your rules do not decide, instead of asking you. |
| Checkpoint | A snapshot of the files a turn changed, so `/undo` and `venom resume` can go back. |
| Compaction | Summarising older turns when the context window fills, keeping facts the session still needs. |
| Extension | A pi extension: code that adds tools, commands or UI to a session. venom's own features are extensions. |
| Harness | `@venom/harness`, the library that runs agent sessions with permissions, subagents and the orchestrator provider. The CLI, `venom serve` and `venom acp` are built on it. |
| Hook | A command or script run on a session event (before a tool call, at the end of a turn). |
| Inbox | The queue of things waiting for a person: approvals, questions, finished background work. |
| Intent | A recorded goal with constraints, acceptance checks and an optional budget, which an agent claims and closes with evidence. |
| Lease | The record of which machine may write to a session. Handing a session to another machine moves the lease and bumps its epoch. |
| Permission mode | How much the agent may do without asking: `plan`, `default`, `accept-edits`, `auto`, `yolo`. |
| pi | The open-source agent framework the venom CLI is a distribution of. venom extends it through its extension API and never forks it. |
| Plugin | A pi package or Claude Code plugin venom loads: extensions, skills, commands, themes. |
| Policy | An organisation's signed rules file (`venom.policy/v1`) that every venom on a machine obeys, above the user's own rules. |
| Sandbox | The OS-level confinement (Seatbelt on macOS, bubblewrap on Linux) that limits what shell commands may write and where they may connect. |
| Session | One conversation with an agent, with its transcript, model, permission mode and working directory. |
| Skill | A folder with a `SKILL.md` that the agent loads when a task matches its description. |
| Subagent | A child session the main agent starts for a task, with its own context and model, reporting back a result. |
| Workflow | A script that runs several agents in steps, such as review then verify. |
| Workspace | A git worktree a session or subagent works in, so parallel work does not collide. |

## Venom Cloud and the mesh {#cloud}

| Term | Meaning |
|---|---|
| Admin key | A `vak_` key for an organisation's admin API. |
| Client key | A `vck_` key for Venom Cloud's `/v1` API, scoped to a key group, with its own limits and budget. |
| Daemon | An orchestrator running in mesh mode, joined to Venom Cloud. It dials out to the cloud; the cloud never connects in. |
| Direct mode | The client sends tokens straight to a reachable daemon with a short-lived ticket; the cloud only authorises. |
| Join token | A one-time `vjt_` token that enrolls a daemon with an organisation. |
| Key group | A group inside an organisation that holds API keys, daemons, policies and GPU grants, not people. The API calls it a `team` (`team_id`, `/api/admin/v1/teams`); teams of people are [org teams](/docs/cloud/teams.md). |
| Mesh mode | The orchestrator's mode when `VENOM_CLOUD_URL` is set: it takes jobs from Venom Cloud as well as local requests. |
| Provenance receipt | A daemon's signed statement of what it served (prompt hash, output tokens, counts), checked by the public mesh. |
| Public mesh | Daemons run by anyone, admitted after verification and audited by sampling, for organisations that accept them. |
| Relay | The path in which tokens flow from the daemon through the cloud to the client, used when no daemon endpoint is reachable. |
| Spend cap | An organisation's monthly limit on total spend, above key group and key budgets. |
| Ticket | A short-lived signed token the cloud issues so a client can call a daemon directly. |

## Protocols {#protocols}

| Term | Meaning |
|---|---|
| ACP | Agent Client Protocol: JSON-RPC over stdio between an editor and an agent. `venom acp` speaks it. |
| MCP | Model Context Protocol: how agents call external tool servers. venom is an MCP client, and `venom browser mcp` is an MCP server. |
| OpenAI-compatible | Accepting OpenAI's `/v1` request and response shapes, so OpenAI SDKs work unchanged. The orchestrator and Venom Cloud are. |
| SSE | Server-Sent Events: the streaming format of `/v1` chat streams and of `venom serve` session events. |

## Related

- [Architecture, ports and contracts](/docs/reference/architecture.md)
- [x-venom headers](/docs/reference/headers.md)
