Glossary
Short definitions of the words venom's docs, config and APIs use, from alias and gear to daemon, relay and lease.
Terms are grouped by where you meet them. Within a group they are alphabetical.
Models and 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
| 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
| 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. |
| 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
| 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. |