Skip to content
Docs menu

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.

View .md

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.whl

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

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.