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.
Two clients ship with venom. Both follow the OpenAPI contract and are tested against it, so every operation has a method, except the browser-only routes (x-venom-browser) of the IDE and phone pages.
Python: venom-client
Standard library only, Python 3.9 or newer. make libs builds the wheel next to the npm tarballs; install it with pip.
pip install venom_client-<version>-py3-none-any.whlOne 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
def approve(req): # each approval_request
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/app", "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 each approval with approve, and returns a RunResult: text, error, usage (summed over the run; usage.cost is USD at list price), turns, approvals (each request with the decision sent) and session_id. It closes the session it opened. Pass session_id= to reuse an open one (kept open unless close=True). on_event sees every event.
approve may return a decision dict (action, feedback, rule, rules), an action string, True (allow once), False (deny) or None (leave it to the timeout). Without approve, every request is denied at once.
Methods
| Method | Operation |
|---|---|
health(), openapi(), prove_server() |
getHealth, getOpenApi, proveServer |
create_session(cwd, *, mode, model, rules, compat, persist, trust_project, thinking_level, tools, append_system_prompt, subagents, planning, sandbox, approval_timeout_ms, resume) |
createSession |
list_sessions(), get_session(id), close_session(id) |
listSessions, getSession, closeSession |
prompt(id, message, streaming_behavior=None, images=None) |
prompt |
steer(id, msg), follow_up(id, msg), abort(id), set_mode(id, mode) |
steer, followUp, abort, setMode |
events(id, after=None, *, reconnect=True, max_retries=5) |
streamEvents |
approvals(id), decide(id, approval_id, action, feedback=None, rule=None, rules=None) |
listApprovals, decideApproval |
questions(id), answer_question(id, question_id, answers) |
listQuestions, answerQuestion |
checkpoints(id), changes(id, turn), transcript(id, limit=None) |
listCheckpoints, getChanges, getTranscript |
agents(id, top=None), agent(id, pid), signal_agent(id, pid, signal, tree=False, reason=None), switch_model(id, pid, model) |
listAgents, getAgent, signalAgent, switchAgentModel |
saved_sessions(cwd=None, limit=None) |
listSavedSessions |
handoff(id), import_session(bundle, cwd=None, force=False) |
handoff, importSession |
workflows(cwd) |
listWorkflows |
schedules(), run_schedule(name), schedule_runs(schedule=None, limit=None), schedule_run_output(run_id, file) |
listSchedules, runSchedule, listScheduleRuns, getScheduleRunOutput |
inbox(), inbox_item(id), resolve_inbox_item(id, action, message=None) |
listInbox, getInboxItem, resolveInboxItem |
create_pairing(), mobile_inbox() |
createPairing, getMobileInbox |
evidence(root, base=None), board(), gears() |
getEvidence, getBoard, listGears |
Responses are plain dicts typed as TypedDicts in venom_client.types (SessionState, PromptAccepted, ApprovalRequest, …). types.EVENT_TYPES lists every documented event type by source, and types.HARNESS_EVENT_TYPES maps each harness event to its TypedDict. Read fields marked "added" in the spec with .get(): older servers don't send them.
Event streams
events() parses SSE with venom_client.SSEParser. When the connection drops (EOF, a reset, or silence longer than stream_timeout, 60 s by default), it reconnects with Last-Event-ID after the server's retry delay, doubling on each consecutive failure up to 30 s. After max_retries failures in a row it raises VenomConnectionError. HTTP errors such as 401, or 404 once the session is gone, are raised, not retried. The iterator ends after session_closed.
Errors
Every non-2xx answer raises a VenomAPIError subclass with status, code (the server's) and message. Everything derives from VenomError.
| Status | Class |
|---|---|
| 400 | BadRequestError |
| 401 | AuthenticationError |
| 403 | PermissionDeniedError |
| 404 | NotFoundError |
| 409 | BusyError |
| 413 | PayloadTooLargeError |
| 429 | TooManySessionsError |
| 5xx | ServerError |
| network | VenomConnectionError |
asyncio
import asyncio
from venom_client import AsyncVenomClient, arun
async def main():
client = AsyncVenomClient("http://127.0.0.1:8790", token)
result = await arun(client, "/home/me/work/app", "Fix it.", approve=lambda r: False)
print(result.text)
asyncio.run(main())AsyncVenomClient has the same methods as coroutines, and events() is an async iterator. Neither client reads HTTP_PROXY or HTTPS_PROXY: both connect straight to the URL you give.
TypeScript: HarnessClient
@venom/harness-server/client is a fetch-only client with no dependencies, for Node 22+, Deno, Bun and browsers. make libs builds venom-harness-server-<v>.tgz (install it with venom-harness-<v>.tgz next to it).
import { HarnessClient, HarnessServerError } from "@venom/harness-server/client";
const client = new HarnessClient({ baseUrl: "http://127.0.0.1:8790", token: process.env.VENOM_SERVER_TOKEN! });
await client.proveServer();
const s = await client.createSession({ cwd: "/home/me/work/app", mode: "default" });
try {
const { text, error } = await client.run(s.id, "Make the failing test pass.", {
approve: (req) => (req.tool === "read" ? { action: "allow-once" } : undefined),
answer: (q) => q.questions.map(() => ({ selected: [], text: "Use your judgement." })),
onEvent: (e) => e.type === "tool_execution_start" && console.log("tool", e.toolName),
});
console.log(error ?? text);
} catch (e) {
if (e instanceof HarnessServerError) console.error(e.status, e.code, e.message);
} finally {
await client.closeSession(s.id);
}run(id, message, opts) sends the prompt and follows its events until its prompt_end, calling approve for each approval and answer for each question; returning undefined leaves the request to the timeout. It resolves with {text, error?, truncated?} (truncated: the final reply was cut off at the output-token limit). opts.signal aborts the wait, opts.streamingBehavior sends it while a run is active.
events(id, {after, signal}) is an async generator over the session's events; it ends after session_closed and does not reconnect by itself, so resume with after set to the last seq you saw. Every other method maps to one operation: health, listSessions, createSession, getSession, closeSession, prompt, steer, followUp, abort, setMode, switchModel, listApprovals, decide, listQuestions, answerQuestion, listCheckpoints, getChanges, getTranscript, listAgents, getAgent, signalAgent, listSavedSessions, handoff, handoffBundle (bytes plus epoch and session), importSession, listWorkflows, listSchedules, runSchedule, listScheduleRuns, scheduleRunOutput, listInbox, getInboxItem, resolveInboxItem, createPairing, mobileInbox, getEvidence, getBoard, listGears. A non-2xx answer throws HarnessServerError with status, code and message; a failed proof throws ServerProofError.
The library
@venom/harness-server has three entry points:
| Export | What |
|---|---|
@venom/harness-server |
The server: createHarnessServer, runServe and parseServeArgs (what venom serve runs), ROUTES, the brokers (ApprovalBroker, QuestionBroker), Scheduler, MatrixBridge, MobileAuth, plus everything from the client |
@venom/harness-server/client |
HarnessClient, proveServer, expectedProof and the request, response and event types |
@venom/harness-server/openapi.yaml |
The contract |
See Embedding the server for a server inside your own process.