Skip to content
Docs menu

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.

View .md

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 ~/work

It 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_end closes it. See Events.
  • When the permission policy says "ask", the server publishes an approval_request event 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_TOKEN must 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/proof first, 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 403 host_not_allowed. A non-loopback bind skips the check: your proxy owns the name.
  • Roots. A session's cwd must be an absolute path to an existing directory whose real path (symlinks resolved) is a --root or inside one. Relative paths, .. escapes, symlinks out of a root and sibling-prefix tricks (/work/repo-evil against /work/repo) are refused with 403 root_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-sudo accepts it, else 403 sudo_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_TOKEN to 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 rewriting Host, or a DNS name). Bind the address the proxy uses with --host, or send Host: localhost.
  • 403 root_not_allowed. The cwd resolves outside every --root. Pass the parent directory as a root, and use an absolute path.
  • 409 busy on a prompt. A run is active. Send it with streamingBehavior (steer or followUp), use /steer or /follow_up, or wait for prompt_end.
  • Approvals are denied without anyone answering. Nobody answered before expiresAt. Raise --approval-timeout, or pass approvalTimeoutMs at create.

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.