Skip to content
Docs menu

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.

View .md

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"]:
        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

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.