Architecture, ports and contracts
How venom's pieces fit together, which port each one listens on, and which file is the contract between them.
Venom is a coding agent plus the stack behind it. Each piece runs on its own and talks to the next over a documented contract, so you can replace any of them with your own.
The layers
app in any language ──HTTP + SSE──▶ venom serve (@venom/harness-server) ─┐
Zed or another ACP editor ──ACP over stdio──▶ venom acp (@venom/acp) ────┤
your Node app ───────────────────────────────────────────────────────────┤
venom CLI (terminal UI) ─────────────────────────────────────────────────┴──▶ @venom/harness ──▶ pi SDK
│ (agent loop, tools, sessions)
▼ OpenAI API (+ x-venom-session)
orchestrator ──▶ vLLM, SGLang, llama.cpp, Ollama, providers
▲
Venom Cloud ──relay or direct──┘ (optional: the orchestrator in mesh mode dials out)| Piece | What it is | Contract |
|---|---|---|
Harness (@venom/harness) |
The library that decides what an agent may do and how it is wired: permission engine, Claude Code compatibility, subagents, plan state, the orchestrator provider. No global state, so many sessions run in one process. | its exports and docs/build-an-agent-app.md |
| venom CLI | The terminal agent, one consumer of the harness. A distribution of pi: it runs pi's own main() with venom's extensions. |
the CLI's flags and venom.yaml |
venom serve |
Harness sessions over HTTP + Server-Sent Events for apps that are not Node. | packages/harness-server/openapi.yaml; generated reference at /docs/api/harness-server |
venom acp |
The same sessions as an Agent Client Protocol agent on stdio, for editors. | the ACP spec |
| Orchestrator | A Go gateway with an OpenAI-compatible API in front of every inference backend you own, with routing, fallback, budgets and usage in SQLite. | the "Orchestrator HTTP API" section of docs/architecture.md; generated reference at /docs/api/orchestrator |
| Web console | A Next.js console over the orchestrator's admin API. | the admin API |
| Venom Cloud | An optional control plane that authenticates organisations and their keys and routes /v1 requests to daemons (orchestrators in mesh mode), directly or through a relay. Provider keys stay on the daemons unless an org chooses otherwise. |
docs/cloud-mesh.md; generated reference at /docs/api/cloud |
Nothing above requires the internet. A laptop with a local model and the orchestrator is a complete system; Venom Cloud and mesh mode exist only when VENOM_CLOUD_URL is set.
Ports
Every port binds to 127.0.0.1 unless you change it.
| Service | Port | What listens there |
|---|---|---|
| orchestrator | 8787 | /v1/* OpenAI-compatible API, /admin/v1/* admin API, /metrics, /healthz, /readyz. Compose publishes it on the host's 127.0.0.1 (VENOM_PORT). |
| web console | 3000 | The Next.js console, password login. Compose binds it to WEB_BIND (default 127.0.0.1) and WEB_PORT. |
| ollama | 11434 | Optional local inference (compose profile local). |
| llama.cpp | 8080 | Optional CPU inference (profile local), no auth, so loopback only. |
| vllm | 8000 | Optional GPU inference (compose profile gpu). |
| prometheus | 9090 | Optional (profile observability); scrapes the orchestrator's /metrics. |
| grafana | 3001 | Optional (profile observability); a provisioned dashboard, anonymous viewer. |
| searxng | 8888 | Optional (profile search); the orchestrator's first web search backend. It forwards queries to public search engines, so it is opt-in. |
| llmfit serve | 8789 | Optional, on the host: hardware and model-fit estimates for the local models page. |
venom serve |
8790 | The harness server, on the host only. |
| Venom Cloud (local dev) | 3100 | make cloud-dev (next dev). In production it runs on Vercel. |
| cloud Postgres (local dev) | 5433 | make cloud-db. Neon in production. |
| cloud daemon (local dev) | 8788 | make cloud-daemon: an orchestrator in mesh mode with its own data directory. |
| browser extension relay | 18765 | venom --chrome-extension (VENOM_BROWSER_RELAY). |
Request path from the CLI
- venom registers an OpenAI chat-completions provider pointed at
VENOM_BASE_URLand lists models fromGET /v1/models. - It picks the model as
--model, thenVENOM_MODEL, thendefaultModelin settings, thenvenom-default. A reopened session keeps its own model. - Every request carries
x-venom-session, so the orchestrator keeps the session on one upstream and its prompt cache stays warm. A subagent is its own session and also sendsx-venom-parent-session, so usage rolls up under the parent. - Side requests (the auto-mode reviewer, prompt hooks, image descriptions, decisions) send
x-venom-session: <session>:<kind>, and the orchestrator applies that kind's defaults (a smaller output cap, lower effort). - A gear with a route profile adds
x-venom-profileto every request of the session. - The orchestrator routes the alias to a target, falls back on failure, and answers with
x-venom-upstream,x-venom-modeland, when it fell back,x-venom-fallback. The CLI's call meter reads them.
x-venom headers lists every header in this exchange.
Compose profiles
docker-compose.yml is target-neutral. make up starts the orchestrator and console; the rest are behind profiles: local (Ollama and llama.cpp), gpu (vLLM), search (SearxNG), observability (Prometheus and Grafana), cloud (the local cloud's Postgres), audit (the public mesh auditor). Dev-only source mounts live in docker-compose.dev-orchestrator.yml and docker-compose.dev-web.yml, added when ORCH_TARGET or WEB_TARGET is dev (the default; prod builds the static binary and the standalone console).
Where the full contracts live
The source repository is private; these files are named so you can ask for them or read them in a release:
| File | What it pins down |
|---|---|
docs/architecture.md |
Ports, environment variables, the orchestrator's HTTP API, routing semantics, model aliases, route profiles, gears. |
packages/harness-server/openapi.yaml |
Every venom serve operation and schema. Also served by a running server at GET /v1/openapi.yaml. |
docs/cloud-mesh.md |
Venom Cloud's API, the daemon protocol, relay and direct mode, budgets, errors. |
config/orchestrator.yaml |
The shipped upstreams, routes, profiles and gears. |
docs/venom-config.schema.json |
The JSON Schema of venom.yaml. |