Python client (venom-client)
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.
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 section documents every operation, and /docs/api/harness-server is the generated reference.
Install and start a server
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:
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
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
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
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 TypedDicts in venom_client.types.
Server and discovery
| 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
| 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
| 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). |
Approvals and questions
| 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
| 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
| 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
| 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
| 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
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"]:
breakevents() 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
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
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:
venom serve, its flags, auth and every operation. - Environment variables for clients:
VENOM_SERVER_URLin the examples. - Embedding the harness: the same sessions in-process from TypeScript.