---
title: Sessions
description: Create, prompt, steer, abort, resume, hand off and close venom serve sessions, and read their transcript.
section: server-api
order: 10
audience: [builder, agent]
sources: [packages/harness-server/openapi.yaml, packages/harness-server/src/session.ts, packages/harness-server/src/server.ts, docs/adr/0024-session-handoff.md]
features: [server-api.sessions, server-api.sessions-prompt, server-api.sessions-steer, server-api.sessions-follow-up, server-api.sessions-abort, server-api.sessions-mode, server-api.sessions-transcript, server-api.sessions-handoff, server-api.saved-sessions, server-api.projects]
---

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

`POST /v1/sessions` (`createSession`) opens a session and answers 201 with its state.

```bash
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}'
```

```python
s = client.create_session("/home/me/work/app", mode="default",
                          rules={"allow": ["bash(npm test:*)"]}, persist=True)
```

```ts
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](#saved)). 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](/docs/cloud/agent-defaults)). |
| `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 {#prompt}

`POST /v1/sessions/{sessionId}/prompt` (`prompt`) sends a message. It answers 202 at once:

```json
{ "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.

```bash
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."}'
```

```python
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"]); break
```

```ts
const 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 {#steer}

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

```bash
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 {#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`.

```python
client.set_mode(sid, "accept-edits")
```

To change the model, see [Agents](/docs/server-api/agents.md#model).

## Transcript {#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.

```python
for item in client.transcript(sid, limit=50)["items"]:
    print(item["role"], item["text"][:80])
```

## Close {#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 {#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](/docs/deploy/projects.md) serves the folders its owner added this way.

```bash
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}
```

```python
for p in client.projects()["projects"]:
    print(p["path"], p.get("branch", ""))
```

## Saved sessions and resume {#saved}

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`:

```bash
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-…"}'
```

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

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.

1. `POST /v1/sessions/{sessionId}/handoff` (`handoff`) on the source stops taking writes, waits for a running turn (up to 30 s, else 409 `busy`), and streams the bundle as `application/octet-stream`. The headers `x-venom-session` and `x-venom-epoch` name the session and the lease epoch it moves to. The source session stays open but read-only: prompt, steer and follow-up answer 409 `lease_lost`.
2. `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=1` replaces a copy already there. It answers 201 with the open session, holding the lease at the next epoch.

```bash
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.bundle
```

```python
bundle = client.handoff(sid)
other.import_session(bundle, cwd="/home/me/work/app")
```

```ts
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](/docs/server-api/events.md): what a run streams
- [Approvals and questions](/docs/server-api/approvals-and-questions.md)
- [Files and changes](/docs/server-api/files-and-changes.md): checkpoints and diffs of each turn
- API reference (`/docs/api/harness-server`): every field of every operation
