Server API (venom serve)
Run venom's agent sessions behind HTTP and Server-Sent Events with venom serve, so an app in any language can create sessions, send prompts, stream events and answer approvals.
venom serve runs the venom agent harness as an HTTP server. A client creates a session in a directory, sends it prompts, follows what the agent does over Server-Sent Events (SSE) and answers its permission questions remotely. Any language that can make HTTP requests can drive it; venom ships a Python client and a TypeScript client.
The contract is an OpenAPI 3.1 document. The server serves it at GET /v1/openapi.yaml, and the generated reference lists every operation and schema: API reference (/docs/api/harness-server). These pages are the guide around it.
Quick start
Start a server that may open sessions under ~/work:
export VENOM_SERVER_TOKEN=$(openssl rand -hex 32)
export VENOM_BASE_URL=http://localhost:8787/v1 # the model endpoint, as for the venom CLI
venom serve --root ~/workIt listens on http://127.0.0.1:8790. Create a session, send a prompt and stream the run:
TOKEN=$VENOM_SERVER_TOKEN
SID=$(curl -s -X POST http://127.0.0.1:8790/v1/sessions \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d "{\"cwd\": \"$HOME/work/app\", \"mode\": \"default\"}" | jq -r .id)
curl -s -X POST http://127.0.0.1:8790/v1/sessions/$SID/prompt \
-H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"message": "Explain what this repository does."}'
curl -N http://127.0.0.1:8790/v1/sessions/$SID/events?after=0 \
-H "Authorization: Bearer $TOKEN"The same in Python, with an approval policy of your own:
import os
from venom_client import VenomClient, run
client = VenomClient("http://127.0.0.1:8790", os.environ["VENOM_SERVER_TOKEN"])
result = run(client, os.path.expanduser("~/work/app"), "Make the failing test pass.",
approve=lambda req: "allow-once" if req["tool"] == "read" else "deny")
print(result.text, result.usage.cost)And in TypeScript:
import { HarnessClient } from "@venom/harness-server/client";
const client = new HarnessClient({ baseUrl: "http://127.0.0.1:8790", token: process.env.VENOM_SERVER_TOKEN! });
const s = await client.createSession({ cwd: "/home/me/work/app", mode: "default" });
const { text } = await client.run(s.id, "Make the failing test pass.", {
approve: (req) => (req.tool === "read" ? { action: "allow-once" } : { action: "deny" }),
});
console.log(text);How it works
- Each session is its own harness and agent: a permission mode, rules, a workspace (
cwd) and an event log. Sessions never share state. - A prompt returns at once (202). The run's output arrives on the session's event stream;
prompt_endcloses it. See Events. - When the permission policy says "ask", the server publishes an
approval_requestevent and waits for your answer. No answer before it expires is a denial. See Approvals and questions. - What a client may not set: the model provider (base URL, key), state directories, the audit sink, the sandbox network policy and the hooks runner. Those are the server's, so a client can't point the agent at another model server.
Authentication
Every route needs Authorization: Bearer $VENOM_SERVER_TOKEN except GET /v1/health, GET /v1/openapi.yaml, POST /v1/auth/proof, the phone inbox page GET /v1/mobile and its pairing POST /v1/mobile/session. The other /v1/mobile/* routes also take a paired phone's cookie (Phone inbox).
- The token is required, always.
VENOM_SERVER_TOKENmust be 16 characters or more, or the server does not start, on loopback too: any local process and any browser page (through DNS rebinding) can reach 127.0.0.1. It is compared in constant time. No CORS headers are sent. - The server can prove it holds the token. A client that did not start the server sends a fresh nonce to
POST /v1/auth/prooffirst, without the token, and checks the answer before sending anything else. See Operations. - Host check. On a loopback bind every request, public routes included, must name this machine in
Host(localhost,*.localhost, 127.0.0.0/8,[::1],host.docker.internal, or no Host). Anything else is 403host_not_allowed. A non-loopback bind skips the check: your proxy owns the name. - Roots. A session's
cwdmust be an absolute path to an existing directory whose real path (symlinks resolved) is a--rootor inside one. Relative paths,..escapes, symlinks out of a root and sibling-prefix tricks (/work/repo-evilagainst/work/repo) are refused with 403root_not_allowed. - What the token grants. A token holder is the operator: it can choose
yolo, add allow rules, trust a project's hooks (trustProject) and answer approvals. Treat it like an SSH key to the roots. The hard-deny list, protected paths and the OS sandbox still apply. Sudo mode (no prompts, bash without the sandbox) is the one thing the token does not grant: only a server started with--allow-sudoaccepts it, else 403sudo_forbidden.
venom serve options
venom serve [--root <dir>]... [--host <addr>] [--port <n>] [options]
venom serve pair [--url <url>] [--json]| Flag | Default | What it does |
|---|---|---|
--root <dir> |
the current directory | An allowed workspace root; sessions may only open inside one. Repeatable. |
--host <addr> |
127.0.0.1 |
Listen address. A non-loopback address prints a warning: the server speaks plain HTTP, so put TLS in front. |
--port <n> |
8790 |
Port; 0 picks a free one. |
--max-sessions <n> |
8 |
Concurrent sessions; one more is 429 too_many_sessions. |
--max-connections <n> |
the larger of 64 and 4 × --max-sessions |
Open TCP connections, event streams included. A request on a connection past the cap is answered 503 too_many_connections with Retry-After: 1. |
--approval-timeout <sec> |
60 |
How long an approval request waits before it is denied. A session's approvalTimeoutMs is capped at the larger of this and 10 minutes. |
--idle-timeout <min> |
30 |
Close sessions unused this long (never while running, streaming or waiting on an approval); 0 never closes them. |
--allow-sudo |
off | Let clients ask for sudo mode at create or with PUT /mode. |
--holder <label> |
VENOM_SERVE_HOLDER, else the host name |
This server's name as a session lease holder (handoff). Two servers on one machine need different labels. |
--pair |
off | Print a QR code that pairs a phone with the inbox page once listening. |
--public-url <url> |
VENOM_SERVE_PUBLIC_URL, else serve.public_url |
The address phones reach this server at. Pairing links use it. Never detected. |
venom serve pair mints a phone pairing on a running server (Phone inbox). Jobs under schedules: in venom.yaml run on their cron while the server runs (Schedules).
Environment and config
| Name | What |
|---|---|
VENOM_SERVER_TOKEN |
Required bearer token, 16+ characters (openssl rand -hex 32). venom serve pair and the clients send it. |
VENOM_BASE_URL, VENOM_API_KEY, VENOM_MODEL, VENOM_ALIAS_MAP |
The model provider every session uses, as for the venom CLI. A client can't change it. |
VENOM_SERVE_HOLDER |
Default for --holder. |
VENOM_SERVE_PUBLIC_URL |
Default for --public-url; wins over serve.public_url. |
serve.public_url (venom.yaml) |
The address you chose for this machine's server. A project file's value counts only once the project is trusted. With venom cloud login, the team fleet links to <url>/v1/mobile. |
VENOM_SERVE_URL |
Where other programs reach the server: venom serve pair (default http://127.0.0.1:8790) and the web console's Agents pages (compose defaults to http://host.docker.internal:8790). |
VENOM_MATRIX_HOMESERVER, VENOM_MATRIX_TOKEN, VENOM_MATRIX_ROOM, VENOM_MATRIX_USERS |
Bridge the inbox to a Matrix room (Phone inbox). |
VENOM_SEARCH_URL, VENOM_OFFLINE |
VENOM_SEARCH_URL gives every session web_search; VENOM_OFFLINE=1 makes every session offline (no web tools, remote MCP servers off). |
Errors and limits
Every error is JSON with a stable code:
{ "error": { "code": "root_not_allowed", "message": "cwd is outside the server's allowed roots: /tmp" } }| Status | Codes |
|---|---|
| 400 | bad_request, invalid_json, images_not_supported, not_persisted, import_failed, not_text, not_a_file, unknown_model |
| 401 | unauthorized, pairing_invalid |
| 403 | root_not_allowed, policy_forbidden, sudo_forbidden, host_not_allowed, csrf_failed, path_outside, path_protected, read_denied, write_denied |
| 404 | not_found, session_not_found, approval_not_found, question_not_found, saved_session_not_found, checkpoint_not_found, checkpoints_off, checkpoint_gone, agent_not_found, file_not_found, inbox_item_not_found, schedule_not_found, run_not_found, output_not_found, board_off |
| 409 | busy, lease_lost, saved_session_open, schedule_running, inbox_item_resolved, import_failed, handoff_failed |
| 413 | body_too_large, too_large |
| 429 | too_many_sessions |
| 500, 503 | internal, session_create_failed, policy_error, shutting_down, too_many_connections |
Request bodies are capped at 1 MiB; a prompt, which may carry images, at 16 MiB. A handoff bundle may be up to 1 GiB.
Embedding the server
venom serve is a thin wrapper around createHarnessServer from @venom/harness-server. An app can run the same server inside its own process, with its own provider and state directories:
import { createHarnessServer } from "@venom/harness-server";
import { provider } from "@venom/harness";
const server = createHarnessServer({
token: process.env.VENOM_SERVER_TOKEN!,
roots: ["/srv/workspaces"],
port: 0,
harness: { provider: provider.providerOptionsFromEnv(process.env) },
});
const { url } = await server.listen();
console.log(`listening on ${url}`);Without harness.provider, sessions get the env-free default: localhost:8787 with no key. See Clients for the package exports.
Troubleshooting
- The server exits at start with a token error. Set
VENOM_SERVER_TOKENto 16 or more characters. - 403
host_not_allowed. A request to a loopback server used a host name that isn't this machine (a reverse proxy rewritingHost, or a DNS name). Bind the address the proxy uses with--host, or sendHost: localhost. - 403
root_not_allowed. Thecwdresolves outside every--root. Pass the parent directory as a root, and use an absolute path. - 409
busyon a prompt. A run is active. Send it withstreamingBehavior(steerorfollowUp), use/steeror/follow_up, or wait forprompt_end. - Approvals are denied without anyone answering. Nobody answered before
expiresAt. Raise--approval-timeout, or passapprovalTimeoutMsat create.
Related pages
- Sessions, Events, Approvals and questions
- Clients: the Python and TypeScript clients
- Getting started
In this section
- Sessions: Create, prompt, steer, abort, resume, hand off and close venom serve sessions, and read their transcript.
- Events (Server-Sent Events): Follow a venom serve session over Server-Sent Events, replay what you missed, and read the session, harness and server event types.
- Approvals and questions: Answer a venom serve session's permission requests and its ask_user questions from your own code, with timeouts, remembered rules and remote policies.
- Files, checkpoints and the browser IDE: Read each turn's file changes as before and after text, browse and edit a session's workspace over HTTP, and open the browser IDE that venom serve hosts.
- Agent processes: List a session's agent and subagent processes with their rates, signal one to pause, interrupt or stop it, and switch an agent's model mid-session.
- Schedules and workflows over HTTP: List venom serve's scheduled background agents, start one now, read its runs and their output files, and list a workspace's workflow scripts.
- Inbox and phone approvals: Read and answer the host's decision inbox over HTTP, pair a phone with the venom serve inbox page, and bridge the inbox to a Matrix room.
- Health, server proof and host reports: Check venom serve's health, fetch its OpenAPI document, verify a server holds the token before sending it, and read the gears, evidence and board reports.
- Python and TypeScript clients: Drive venom serve from Python with venom-client (sync and asyncio) or from TypeScript with HarnessClient, including run helpers, typed errors and reconnecting event streams.