---
title: Architecture, ports and contracts
description: How venom's pieces fit together, which port each one listens on, and which file is the contract between them.
section: reference
order: 20
audience: [user, operator, builder, agent]
sources: [docs/architecture.md, docker-compose.yml, packages/harness-server/openapi.yaml, docs/cloud-mesh.md]
features: [reference.architecture]
---

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 {#layers}

```text
  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 {#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 {#cli-to-orchestrator}

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](/docs/reference/headers.md) lists every header in this exchange.

## Compose profiles {#compose}

`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 {#contracts}

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`. |

## Related

- [Environment variables](/docs/reference/environment.md)
- [Error codes](/docs/reference/errors.md)
- [Glossary](/docs/reference/glossary.md)
- [Getting started](/docs/getting-started.md)
