Sessions
Create, prompt, steer, abort, resume, hand off and close venom serve sessions, and read their transcript.
A session is one agent working in one directory. It keeps its permission mode, rules, model and an event log until you close it or it sits idle past --idle-timeout. The examples below assume TOKEN holds the server token and S=http://127.0.0.1:8790.
Create a session
POST /v1/sessions (createSession) opens a session and answers 201 with its state.
curl -s -X POST $S/v1/sessions -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"cwd": "/home/me/work/app", "mode": "default", "rules": {"allow": ["bash(npm test:*)"]}, "persist": true}'s = client.create_session("/home/me/work/app", mode="default",
rules={"allow": ["bash(npm test:*)"]}, persist=True)const s = await client.createSession({ cwd: "/home/me/work/app", mode: "default", rules: { allow: ["bash(npm test:*)"] }, persist: true });| Field | Type | Default | What |
|---|---|---|---|
cwd |
string | required | Workspace directory: absolute, existing, inside a --root after symlinks. |
mode |
plan, default, accept-edits, auto, yolo, sudo |
default |
The permission mode. sudo needs a server started with --allow-sudo and is never saved or restored. |
model |
string | venom-default |
A model id on the server's provider. The provider itself is server configuration. |
rules |
{allow, ask, deny} of string arrays |
none | Permission rules for this session, such as bash(npm test:*). |
compat |
boolean or object | all sources | Which Claude Code compatibility sources to load: false none, or per source (memory, skills, commands, agents, mcp, settings, hooks, plugins, user). |
persist |
boolean | false |
Save the transcript as JSONL under the server's agent dir, so it can be resumed or handed off. |
trustProject |
boolean | false |
Trust the project's hooks, MCP servers and allow rules. |
thinkingLevel |
off, minimal, low, medium, high, xhigh |
the provider's | Reasoning effort. |
tools |
string array | all | Restrict the active tools. |
appendSystemPrompt |
string array | none | Text appended to the system prompt. |
subagents |
boolean | true |
The task tool. |
planning |
boolean | true |
Plan mode and the todo tool. |
sandbox |
boolean or auto |
auto (on in yolo) |
The OS sandbox for bash. |
approvalTimeoutMs |
integer ≥ 1000 | the server's (60 s) | How long an approval waits before it is denied; capped by the server. |
resume |
string | none | Continue a saved session (Saved sessions). Implies persist. |
venomMcp |
{url, key, products?} or false |
the host's venom cloud login |
Venom Cloud's product MCP servers with this session's own key; false connects none. The key goes only into those servers' Authorization header (What agents connect to by default). |
cloudInference |
{url, key} |
none (the server's provider) | Venom Cloud's inference for this session (added 2026-11): its model requests go to <url>/v1 with this key and x-venom-daemon: cloud, so the cloud serves them from its own providers and never relays them back to a daemon. Venom Cloud sends it when a chat's gear runs on cloud keys (Venom Agents: where a daemon chat's model runs). The key goes only into those requests' Authorization header, never into the state, events, transcript or prompt; the OS sandbox keeps the server's own orchestrator, so commands don't reach the cloud through it. 403 policy_forbidden when the organisation policy pins the orchestrator. GET /v1/gears says cloudInference: true on a server that takes it. |
The response is the session state, the same object GET /v1/sessions (listSessions) lists and GET /v1/sessions/{sessionId} (getSession) returns: id, cwd, mode, model (provider/id), status (idle or running), createdAt, lastEventId, pendingApprovals, approvalTimeoutMs, and when known messageCount, sandboxActive, projectTrusted, persisted, sessionFile, piSessionId and imageInput. piSessionId is the id the venom provider sends as x-venom-session, so you can find the session's requests in the orchestrator's logs. imageInput says the model takes images.
Errors: 400 for a bad body or cwd, 400 unknown_model (added 2026-11: a model the session's provider doesn't serve; the message names the ones it does, and no session is left behind), 403 root_not_allowed, policy_forbidden (the organisation policy forbids the mode or sandbox: false, or pins the orchestrator while the body has cloudInference) or sudo_forbidden, 404 saved_session_not_found, 409 saved_session_open, 429 too_many_sessions, 500 policy_error (the policy file is invalid or its audit log can't be written).
Prompt
POST /v1/sessions/{sessionId}/prompt (prompt) sends a message. It answers 202 at once:
{ "promptId": "p_3f2a", "disposition": "started", "lastEventId": 41 }disposition is started (a run began; its prompt_end event carries the same promptId), queued or handled (a slash command the harness answered itself). Open the event stream with ?after=<lastEventId> and you miss nothing.
curl -s -X POST $S/v1/sessions/$SID/prompt -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"message": "Run the tests and fix what fails."}'accepted = client.prompt(sid, "Run the tests and fix what fails.")
for event in client.events(sid, after=accepted["lastEventId"]):
if event["type"] == "prompt_end" and event["promptId"] == accepted["promptId"]:
print(event["text"]); breakconst accepted = await client.prompt(s.id, "Run the tests and fix what fails.");
for await (const e of client.events(s.id, { after: accepted.lastEventId })) {
if (e.type === "prompt_end" && e.promptId === accepted.promptId) { console.log(e.text); break; }
}While a run is active a plain prompt is 409 busy. Pass streamingBehavior: steer (delivered after the current turn's tool calls) or followUp (delivered when the agent would otherwise stop).
Images. For a model that takes images (imageInput: true), images carries up to 8 {data, mimeType} objects: base64 bytes (no data: prefix) of image/png, image/jpeg, image/gif or image/webp. The bytes must match the declared type and the image may be at most 20000 px a side and 50 megapixels, else 400 bad_request. A model without image input answers 400 images_not_supported. The transcript counts images but never sends them back.
Steer, follow up, abort
| Operation | Route | Body | Answer |
|---|---|---|---|
steer |
POST /v1/sessions/{sessionId}/steer |
{"message": "…"} |
{disposition: queued | handled}; delivered after the current turn's tool calls |
followUp |
POST /v1/sessions/{sessionId}/follow_up |
{"message": "…"} |
{disposition}; delivered when the agent would otherwise stop |
abort |
POST /v1/sessions/{sessionId}/abort |
none | {aborted: true} once the session is idle |
curl -s -X POST $S/v1/sessions/$SID/steer -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"message": "Only touch src/, not the tests."}'
curl -s -X POST $S/v1/sessions/$SID/abort -H "Authorization: Bearer $TOKEN"Python: client.steer(sid, msg), client.follow_up(sid, msg), client.abort(sid). TypeScript: client.steer(id, msg), client.followUp(id, msg), client.abort(id).
Change the mode
PUT /v1/sessions/{sessionId}/mode (setMode) with {"mode": "accept-edits"} answers {mode, previous} and emits a mode event. 403 policy_forbidden for a mode the organisation policy doesn't allow; 403 sudo_forbidden for sudo on a server without --allow-sudo.
client.set_mode(sid, "accept-edits")To change the model, see Agents.
Transcript
GET /v1/sessions/{sessionId}/transcript?limit=200 (getTranscript) returns the conversation as text: {items, total}. Each item has role (user, assistant, toolResult) and text (first 64 KiB), and where they apply thinking, toolCalls (id, name, args), toolCallId, toolName, isError, images (a count), timestamp and truncated. limit keeps the newest items: default 200, at most 1000.
for item in client.transcript(sid, limit=50)["items"]:
print(item["role"], item["text"][:80])Close
DELETE /v1/sessions/{sessionId} (closeSession) answers {closed: true}. It denies pending approvals, aborts the run (the running command's process group is killed), stops the session's egress proxy and language servers, and ends every event stream with session_closed. Idle sessions close by themselves after --idle-timeout, and every session closes on SIGINT or SIGTERM.
Projects
GET /v1/projects (listProjects, added 2026-11) lists the folders a client can open a session in: each of the server's roots (--root), then the git repositories directly under one (one level, by name; hidden directories and node_modules are skipped, and a symlink only counts when it resolves inside the same root). It reads directory entries and .git/HEAD only: no file contents, no git process.
| Field | What |
|---|---|
name |
The directory's own name. |
path |
Its absolute, canonical path: pass it as cwd to POST /v1/sessions. |
root |
The root it is, or sits directly under. |
git |
Whether it is a git repository (a .git directory, or a .git file for a linked worktree). |
branch |
The branch its HEAD points at; absent when it is not a repository or HEAD is detached. |
At most 500 entries; truncated: true says some were left out. The desktop daemon serves the folders its owner added this way.
curl -s $S/v1/projects -H "Authorization: Bearer $TOKEN"
# {"projects":[{"name":"work","path":"/home/me/work","root":"/home/me/work","git":false},
# {"name":"app","path":"/home/me/work/app","root":"/home/me/work","git":true,"branch":"main"}],"truncated":false}for p in client.projects()["projects"]:
print(p["path"], p.get("branch", ""))Saved sessions and resume
A session created with persist: true is saved under the server's agent dir (default ~/.venom/agent, where the terminal keeps its sessions too). GET /v1/saved-sessions (listSavedSessions) lists them, newest first, only those whose workspace is inside a root now.
| Query | Default | What |
|---|---|---|
cwd |
all | Only sessions started in this workspace (the same checks as a session's cwd). |
limit |
50 | At most this many, up to 500. |
Each entry has id, cwd, name (set with /name), created, modified, messageCount and firstMessage (its first 200 characters). Resume one by passing its id as resume with the same cwd:
curl -s "$S/v1/saved-sessions?cwd=/home/me/work/app" -H "Authorization: Bearer $TOKEN"
curl -s -X POST $S/v1/sessions -H "Authorization: Bearer $TOKEN" -H 'content-type: application/json' \
-d '{"cwd": "/home/me/work/app", "resume": "0199b6c2-…"}'saved = client.saved_sessions(cwd="/home/me/work/app")
s = client.create_session("/home/me/work/app", resume=saved[0]["id"])The id must belong to that workspace (else 404 saved_session_not_found) and must not be open on this server already (409 saved_session_open; two sessions appending to one file would interleave).
Hand off to another machine
A persisted session can move to another venom serve: its transcript, spill files, checkpoint history and the working tree's uncommitted edits travel in one bundle.
POST /v1/sessions/{sessionId}/handoff(handoff) on the source stops taking writes, waits for a running turn (up to 30 s, else 409busy), and streams the bundle asapplication/octet-stream. The headersx-venom-sessionandx-venom-epochname the session and the lease epoch it moves to. The source session stays open but read-only: prompt, steer and follow-up answer 409lease_lost.POST /v1/sessions/import(importSession) on the target takes the bundle as the body.?cwd=says where to restore (optional when the server has one root); the workspace must be at the same commit and clean.?force=1replaces a copy already there. It answers 201 with the open session, holding the lease at the next epoch.
curl -s -X POST $S/v1/sessions/$SID/handoff -H "Authorization: Bearer $TOKEN" -o session.bundle
curl -s -X POST "http://other-host:8790/v1/sessions/import?cwd=/home/me/work/app" \
-H "Authorization: Bearer $OTHER_TOKEN" -H 'content-type: application/octet-stream' \
--data-binary @session.bundlebundle = client.handoff(sid)
other.import_session(bundle, cwd="/home/me/work/app")const bytes = await client.handoff(s.id);
await other.importSession(bytes, { cwd: "/home/me/work/app" });Errors: 400 not_persisted (the session was not created with persist), 400 import_failed (not a bundle, a bad checksum, another commit, a dirty workspace), 409 import_failed (this machine has the session at an equal or newer epoch), 409 handoff_failed, 413 body_too_large (over 1 GiB). Trust, permission rules and the audit log do not move. The bundle can hold secrets that appeared in tool output: move it over TLS and delete it after the import. Each server names itself with --holder (or VENOM_SERVE_HOLDER).
Related pages
- Events: what a run streams
- Approvals and questions
- Files and changes: checkpoints and diffs of each turn
- API reference (
/docs/api/harness-server): every field of every operation