---
title: Server API (venom serve)
description: 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.
section: server-api
order: 0
audience: [builder, operator, agent]
sources: [packages/harness-server/openapi.yaml, packages/harness-server/src/cli.ts, packages/harness-server/src/server.ts, packages/harness-server/src/auth.ts, packages/harness-server/AGENTS.md, docs/adr/0003-harness-server.md]
features: [server-api.serve]
---

`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](/docs/server-api/clients.md).

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 {#quick-start}

Start a server that may open sessions under `~/work`:

```bash
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:

```bash
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:

```python
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:

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

- 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](/docs/server-api/events.md).
- 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](/docs/server-api/approvals-and-questions.md).
- 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 {#auth}

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](/docs/server-api/mobile-and-inbox.md)).

- **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](/docs/server-api/operations.md#proof).
- **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 {#flags}

```bash
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](/docs/server-api/sessions.md#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](/docs/server-api/mobile-and-inbox.md#pairing)). Jobs under `schedules:` in venom.yaml run on their cron while the server runs ([Schedules](/docs/server-api/schedules-and-workflows.md)).

## Environment and config {#env}

| 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](/docs/server-api/mobile-and-inbox.md#matrix)). |
| `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 {#errors}

Every error is JSON with a stable code:

```json
{ "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 {#embedding}

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

```ts
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](/docs/server-api/clients.md#library) for the package exports.

## Troubleshooting {#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.

## Related pages

- [Sessions](/docs/server-api/sessions.md), [Events](/docs/server-api/events.md), [Approvals and questions](/docs/server-api/approvals-and-questions.md)
- [Clients](/docs/server-api/clients.md): the Python and TypeScript clients
- [Getting started](/docs/getting-started.md)


## In this section {#in-this-section}

- [Sessions](/docs/server-api/sessions.md): Create, prompt, steer, abort, resume, hand off and close venom serve sessions, and read their transcript.
- [Events (Server-Sent Events)](/docs/server-api/events.md): 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](/docs/server-api/approvals-and-questions.md): 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](/docs/server-api/files-and-changes.md): 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](/docs/server-api/agents.md): 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](/docs/server-api/schedules-and-workflows.md): 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](/docs/server-api/mobile-and-inbox.md): 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](/docs/server-api/operations.md): 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](/docs/server-api/clients.md): 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.
