---
title: Python and TypeScript clients
description: 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.
section: server-api
order: 90
audience: [builder, agent]
sources: [clients/python/README.md, clients/python/src/venom_client/client.py, clients/python/src/venom_client/run.py, packages/harness-server/src/client.ts, packages/harness-server/src/index.ts, packages/harness-server/package.json]
features: [server-api.library]
---

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 {#python}

Standard library only, Python 3.9 or newer. `make libs` builds the wheel next to the npm tarballs; install it with pip.

```bash
pip install venom_client-<version>-py3-none-any.whl
```

### One prompt, start to finish {#python-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

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 {#python-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 `TypedDict`s 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 {#python-events}

`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 {#python-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 {#python-async}

```python
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 {#typescript}

`@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).

```ts
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 {#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](/docs/server-api.md#embedding) for a server inside your own process.

## Related pages

- [Server API overview](/docs/server-api.md)
- [Events](/docs/server-api/events.md)
- [Approvals and questions](/docs/server-api/approvals-and-questions.md)
