Skip to content
Docs menu

Architecture, ports and contracts

How venom's pieces fit together, which port each one listens on, and which file is the contract between them.

View .md

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

  1. venom registers an OpenAI chat-completions provider pointed at VENOM_BASE_URL and lists models from GET /v1/models.
  2. It picks the model as --model, then VENOM_MODEL, then defaultModel in settings, then venom-default. A reopened session keeps its own model.
  3. 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 sends x-venom-parent-session, so usage rolls up under the parent.
  4. 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).
  5. A gear with a route profile adds x-venom-profile to every request of the session.
  6. The orchestrator routes the alias to a target, falls back on failure, and answers with x-venom-upstream, x-venom-model and, 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.