Skip to content
Docs menu

Glossary

Short definitions of the words venom's docs, config and APIs use, from alias and gear to daemon, relay and lease.

View .md

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.