---
title: Python client (venom-client)
description: Drive venom serve from Python with the zero-dependency venom-client package, sync or asyncio, with every VenomClient and AsyncVenomClient method, the run() helper, typed errors and reconnecting event streams.
section: integrations
order: 10
audience: [builder, agent]
sources: [clients/python/README.md, clients/python/src/venom_client/client.py, clients/python/src/venom_client/aio.py, clients/python/src/venom_client/run.py, clients/python/pyproject.toml]
features: [integrations.python-client]
---

`venom-client` is a Python client for `venom serve`, which runs venom harness sessions behind HTTP and Server-Sent Events. It uses only the standard library, has no runtime dependencies, and works on Python 3.9 and newer. It has a sync client, `VenomClient`, and an asyncio client, `AsyncVenomClient`, with the same methods.

The contract it follows is the server's OpenAPI document; the [Server API](/docs/server-api.md) section documents every operation, and `/docs/api/harness-server` is the generated reference.

## Install and start a server {#install}

`make libs` (or a release) builds the wheel `venom_client-<version>-py3-none-any.whl` next to the harness's npm tarballs. Install it with pip:

```bash
pip install venom_client-<version>-py3-none-any.whl
export VENOM_SERVER_TOKEN=$(openssl rand -hex 32)
venom serve --root ~/work &
```

## One prompt, start to finish {#run}

```python
import os
from venom_client import VenomClient, run

client = VenomClient("http://127.0.0.1:8790", os.environ["VENOM_SERVER_TOKEN"])
client.prove_server()                      # when you didn't start the server yourself

def approve(req):                          # each approval_request event; runs in your process
    if req["tool"] == "bash" and req["input"].get("command") == "npm test":
        return "allow-once"
    return {"action": "deny", "feedback": "Only `npm test` may run here."}

result = run(client, "/home/me/work/repo", "Make the failing test pass.",
             approve=approve, mode="default", compat=False)
print(result.text, result.error, result.turns)
print(result.usage.input, result.usage.output, result.usage.cache_read, result.usage.cost)
```

`run()` opens a session (extra keyword arguments are `create_session` options), sends the prompt, streams the events, answers every approval request with `approve`, and returns a `RunResult`:

| Field | What |
|---|---|
| `text` | The final answer. |
| `error` | The error, if the run failed. |
| `truncated` | `True` when the final reply was cut off at the output-token limit, so `text` is incomplete. |
| `usage` | Summed over the run's assistant messages: `input`, `output`, `cache_read`, `cost` (USD at the bundled list price of the model that served each message, 0 for local models: the figure `/cost` shows). |
| `turns` | Model calls. |
| `approvals` | Each request with the decision sent. |
| `session_id` | The session it used. |

It closes the session it opened. Pass `session_id=` to reuse an open session; it stays open unless you pass `close=True`. `on_event` sees every event.

`approve` may return a decision dict (`{"action", "feedback"?, "rule"?, "rules"?}`), an action string (`"allow-once"`, `"allow-session"`, `"allow-project"`, `"deny"`), `True` (allow once), `False` (deny) or `None` (leave it unanswered; the server denies it when it expires). `allow-session` and `allow-project` without `rule` or `rules` store the request's own `rules`: one per segment of a compound command, so `npm test | tee out.txt` becomes `bash(npm test:*)` and `bash(tee out.txt:*)`. Without `approve`, every request is denied at once with a reason the model reads.

The asyncio version is `arun()`; its `approve` may be sync or async.

## The client {#client}

```python
VenomClient(url="http://127.0.0.1:8790", token=None, *, timeout=60.0, stream_timeout=60.0)
AsyncVenomClient(url="http://127.0.0.1:8790", token=None, *, timeout=60.0, stream_timeout=60.0)
```

`url` must be `http` or `https`. The token is never shown in the client's `repr`. Neither client reads the environment: pass the URL and token yourself. Neither uses `HTTP_PROXY`, `HTTPS_PROXY` or `ALL_PROXY`; both connect straight to the URL.

## Methods {#methods}

Each method exists on both clients: `VenomClient.<name>` returns the value, `AsyncVenomClient.<name>` is a coroutine with the same arguments (and `events()` is an async iterator there). Responses are plain dicts typed as `TypedDict`s in `venom_client.types`.

### Server and discovery {#methods-server}

| Method | HTTP | What |
|---|---|---|
| `health()` | `GET /v1/health` | Liveness, no auth: `VenomClient.health`, `AsyncVenomClient.health`. |
| `prove_server()` | `POST /v1/auth/proof` | No auth. Raises `ServerProofError` unless the server proves it holds your token. Call it first when you didn't start the server: `VenomClient.prove_server`, `AsyncVenomClient.prove_server`. |
| `openapi()` | `GET /v1/openapi.yaml` | The contract, no auth: `VenomClient.openapi`, `AsyncVenomClient.openapi`. |
| `gears()` | `GET /v1/gears` | The gears the server's venom.yaml offers, each with the model it resolves to: `VenomClient.gears`, `AsyncVenomClient.gears`. |
| `workflows(cwd)` | `GET /v1/workflows` | The workflow scripts of a workspace: `VenomClient.workflows`, `AsyncVenomClient.workflows`. |
| `board()` | `GET /v1/board` | The agent factory's health: board queue, claims, cycle times, gate runs, merge queue: `VenomClient.board`, `AsyncVenomClient.board`. |
| `evidence(root, base=None)` | `GET /v1/evidence` | The `venom.evidence/v1` bundle of the repository at `root`, against `base` (default `HEAD`): `VenomClient.evidence`, `AsyncVenomClient.evidence`. |

### Sessions {#methods-sessions}

| Method | HTTP | What |
|---|---|---|
| `create_session(cwd, *, mode, model, rules, compat, persist, trust_project, thinking_level, tools, append_system_prompt, subagents, planning, sandbox, approval_timeout_ms, resume)` | `POST /v1/sessions` | Open a session in `cwd`. |
| `list_sessions()` | `GET /v1/sessions` | Open sessions: `VenomClient.list_sessions`, `AsyncVenomClient.list_sessions`. |
| `get_session(id)` | `GET /v1/sessions/{id}` | One session's state: `VenomClient.get_session`, `AsyncVenomClient.get_session`. |
| `close_session(id)` | `DELETE /v1/sessions/{id}` | Close it: `VenomClient.close_session`, `AsyncVenomClient.close_session`. |
| `saved_sessions(cwd=None, limit=None)` | `GET /v1/saved-sessions` | Sessions saved with `persist`, newest first, that `create_session(resume=...)` continues: `VenomClient.saved_sessions`, `AsyncVenomClient.saved_sessions`. |
| `transcript(id, limit=None)` | `GET /v1/sessions/{id}/transcript` | `{items, total}`: `VenomClient.transcript`, `AsyncVenomClient.transcript`. |
| `handoff(id)` | `POST /v1/sessions/{id}/handoff` | Hand a persisted session to another machine: returns the bundle bytes, and the session turns read-only here: `VenomClient.handoff`, `AsyncVenomClient.handoff`. |
| `import_session(bundle, cwd=None, force=False)` | `POST /v1/sessions/import` | Take over a handed-off session from those bytes; `force` replaces a copy already here: `VenomClient.import_session`, `AsyncVenomClient.import_session`. |

### Prompting and control {#methods-prompting}

| Method | HTTP | What |
|---|---|---|
| `prompt(id, message, streaming_behavior=None, images=None)` | `POST …/prompt` | Returns `{promptId, disposition, lastEventId}`. `images` is a list of `{"data": <base64>, "mimeType": ...}`. |
| `steer(id, message)` | `POST …/steer` | A message delivered while the agent works: `VenomClient.steer`, `AsyncVenomClient.steer`. |
| `follow_up(id, message)` | `POST …/follow_up` | A message queued for after the current run: `VenomClient.follow_up`, `AsyncVenomClient.follow_up`. |
| `abort(id)` | `POST …/abort` | Abort the running turn; returns once the session is idle: `VenomClient.abort`, `AsyncVenomClient.abort`. |
| `set_mode(id, mode)` | `PUT …/mode` | Switch the permission mode: `VenomClient.set_mode`, `AsyncVenomClient.set_mode`. |
| `events(id, after=None, *, reconnect=True, max_retries=5)` | `GET …/events` | The SSE stream (see [Events and reconnects](#events)). |

### Approvals and questions {#methods-approvals}

| Method | HTTP | What |
|---|---|---|
| `approvals(id)` | `GET …/approvals` | Pending approval requests, the same objects as the `approval_request` events: `VenomClient.approvals`, `AsyncVenomClient.approvals`. |
| `decide(id, approval_id, action, feedback=None, rule=None, rules=None)` | `POST …/approvals/{approvalId}` | Answer one. `NotFoundError` once it timed out or was answered. |
| `questions(id)` | `GET …/questions` | Pending `ask_user` questions: `VenomClient.questions`, `AsyncVenomClient.questions`. |
| `answer_question(id, question_id, answers)` | `POST …/questions/{questionId}` | One `{"selected": [...], "text": "..."}` per question. |

### Changes and checkpoints {#methods-changes}

| Method | HTTP | What |
|---|---|---|
| `checkpoints(id)` | `GET …/checkpoints` | `{enabled, checkpoints: [{entryId, prompt, files, …}]}`, oldest first: `VenomClient.checkpoints`, `AsyncVenomClient.checkpoints`. |
| `changes(id, turn)` | `GET …/changes?turn=` | Each file the turn changed, with `before` and `after` text. Secrets, binaries and files over 256 KiB come back with `omitted` and no text: `VenomClient.changes`, `AsyncVenomClient.changes`. |

### Agent processes {#methods-agents}

| Method | HTTP | What |
|---|---|---|
| `agents(id, top=None)` | `GET …/agents` | The session's agent processes with token rate and tool-call rate, or the `top` N by token rate: `VenomClient.agents`, `AsyncVenomClient.agents`. |
| `agent(id, pid)` | `GET …/agents/{pid}` | One process: `VenomClient.agent`, `AsyncVenomClient.agent`. |
| `signal_agent(id, pid, signal, *, tree=False, reason=None)` | `POST …/agents/{pid}/signal` | `SIGSTOP` parks it at its next turn boundary until `SIGCONT`; `SIGINT` aborts what it is doing (a subagent returns a partial report); `SIGTERM` stops it. `tree` reaches its descendants. |
| `switch_model(id, pid, model)` | `POST …/agents/{pid}/model` | Switch an agent's model, at once when idle, else at its next turn boundary. Returns `{pid, model, applied, cacheLost}`: `VenomClient.switch_model`, `AsyncVenomClient.switch_model`. |

### Inbox and phone {#methods-inbox}

| Method | HTTP | What |
|---|---|---|
| `inbox()` | `GET /v1/inbox` | Open inbox items, most urgent first: `VenomClient.inbox`, `AsyncVenomClient.inbox`. |
| `inbox_item(item_id)` | `GET /v1/inbox/{id}` | One item by id or unique prefix: `VenomClient.inbox_item`, `AsyncVenomClient.inbox_item`. |
| `resolve_inbox_item(item_id, action, message=None)` | `POST /v1/inbox/{id}/resolve` | Answer it; the waiting agent wakes. 404 unknown, 409 already answered, 400 bad action: `VenomClient.resolve_inbox_item`, `AsyncVenomClient.resolve_inbox_item`. |
| `create_pairing()` | `POST /v1/mobile/pairings` | A one-time code that pairs a phone with the inbox page: `VenomClient.create_pairing`, `AsyncVenomClient.create_pairing`. |
| `mobile_inbox()` | `GET /v1/mobile/inbox` | What the phone page shows: open inbox items plus every served session's pending approvals: `VenomClient.mobile_inbox`, `AsyncVenomClient.mobile_inbox`. |

### Schedules {#methods-schedules}

| Method | HTTP | What |
|---|---|---|
| `schedules()` | `GET /v1/schedules` | The scheduled jobs with their next and last run: `VenomClient.schedules`, `AsyncVenomClient.schedules`. |
| `run_schedule(name)` | `POST /v1/schedules/{name}/run` | Start a job now; returns the run as it started: `VenomClient.run_schedule`, `AsyncVenomClient.run_schedule`. |
| `schedule_runs(schedule=None, limit=None)` | `GET /v1/schedules/runs` | Runs, newest first: `VenomClient.schedule_runs`, `AsyncVenomClient.schedule_runs`. |
| `schedule_run_output(run_id, file)` | `GET /v1/schedules/runs/{id}/output` | One file a browser task's run produced (`result.json`, an extract, a download), as bytes: `VenomClient.schedule_run_output`, `AsyncVenomClient.schedule_run_output`. |

## Events and reconnects {#events}

```python
accepted = client.prompt(sid, "Fix the failing test")
for event in client.events(sid, after=accepted["lastEventId"]):   # misses nothing
    if event["type"] == "approval_request":
        client.decide(sid, event["approvalId"], "allow-once")
    elif event["type"] == "prompt_end" and event["promptId"] == accepted["promptId"]:
        break
```

`events()` parses the stream with `venom_client.SSEParser`, which works with any transport. When the connection drops (EOF, a reset, or silence longer than `stream_timeout`; the server pings every 15 s), it reconnects with `Last-Event-ID` after the server's `retry` delay, doubling on each consecutive failure up to 30 s. An event cut off mid-transfer is replayed, not skipped. The server keeps each session's last 2000 events; an older gap starts the replay with `events_dropped`. After `max_retries` failures in a row it raises `VenomConnectionError`. HTTP errors such as 401, or 404 once the session is gone, are raised and not retried. The iterator ends after `session_closed`.

`types.EVENT_TYPES` lists every documented event type by source, and `types.HARNESS_EVENT_TYPES` maps each harness event `type` to its `TypedDict`. Treat an unknown `session` event type as new, not as an error, and read fields marked "added 2026-10" with `.get()`: older servers don't send them.

## Errors {#errors}

Every non-2xx answer raises a `VenomAPIError` subclass carrying `status`, `code` (the server's) and `message`.

| Status | Class | Server codes |
|---|---|---|
| 400 | `BadRequestError` | `bad_request`, `invalid_json`, `prompt_rejected`, `images_not_supported` |
| 401 | `AuthenticationError` | `unauthorized` |
| 403 | `PermissionDeniedError` | `root_not_allowed`, `policy_forbidden` |
| 404 | `NotFoundError` | `session_not_found`, `approval_not_found`, `not_found`, `saved_session_not_found`, `checkpoint_not_found`, `checkpoints_off`, `checkpoint_gone` |
| 409 | `BusyError` | `busy` (a prompt while running, without `streaming_behavior`), `saved_session_open`, `lease_lost` (a handed-off session) |
| 413 | `PayloadTooLargeError` | `body_too_large` (1 MiB; 16 MiB for a prompt) |
| 429 | `TooManySessionsError` | `too_many_sessions` |
| 5xx | `ServerError` | `internal`, `session_create_failed`, `shutting_down`; 503 `too_many_connections` |

Network failures raise `VenomConnectionError`. Everything derives from `VenomError`.

## asyncio {#async}

```python
import asyncio, os
from venom_client import AsyncVenomClient, arun

async def main():
    client = AsyncVenomClient("http://127.0.0.1:8790", os.environ["VENOM_SERVER_TOKEN"])
    result = await arun(client, "/home/me/work/repo", "Fix it.")
    print(result.text)

asyncio.run(main())
```

With no dependencies there is no aiohttp or httpx: the async client carries a small HTTP/1.1 client over asyncio streams (one connection per request, `Content-Length` and chunked bodies, `https` through `ssl`), which is all `venom serve` needs and lets a stream be cancelled cleanly.

## Related

- [Server API](/docs/server-api.md): `venom serve`, its flags, auth and every operation.
- [Environment variables for clients](/docs/integrations.md#env): `VENOM_SERVER_URL` in the examples.
- [Embedding the harness](/docs/harness/embedding.md): the same sessions in-process from TypeScript.
