Files, checkpoints and the browser IDE
Read each turn's file changes as before and after text, browse and edit a session's workspace over HTTP, and open the browser IDE that venom serve hosts.
Every turn that changes files leaves a checkpoint: a snapshot of the workspace before and after, whatever wrote the files (bash included). A client can show each turn's diff exactly, and the browser IDE uses the same routes to show and edit the workspace.
Checkpoints
GET /v1/sessions/{sessionId}/checkpoints (listCheckpoints) lists the session's turn checkpoints, oldest first:
{
"enabled": true,
"checkpoints": [
{ "entryId": "e7c1", "run": "r1", "prompt": "Fix the failing test", "files": ["src/sum.ts"],
"at": 1762164000000, "undone": false, "before": "3f1c9e…", "after": "8a02d4…" }
]
}run is the user message that started the run (one prompt can take several turns), before and after are snapshot commits in the server's shadow store, files lists at most 50 changed paths and more counts the rest, and undone is true while the run is undone (/undo). enabled: false comes with a disabledReason (no git repository, or the server turned checkpoints off). A new checkpoint also shows on the event stream as an entry_appended event with entry.customType: "venom-checkpoint" and entry.id, the same entryId.
A turn's changes
GET /v1/sessions/{sessionId}/changes?turn=<entryId> (getChanges) returns each file that turn changed, with its text before and after:
curl -s "$S/v1/sessions/$SID/changes?turn=e7c1" -H "Authorization: Bearer $TOKEN"for cp in client.checkpoints(sid)["checkpoints"]:
for f in client.changes(sid, cp["entryId"])["files"]:
print(f["status"], f["path"], f.get("omitted") or f"+{f['added']} -{f['removed']}")const { checkpoints } = await client.listCheckpoints(sid);
const turn = await client.getChanges(sid, checkpoints.at(-1)!.entryId);
for (const f of turn.files) console.log(f.status, f.path, f.omitted ?? `+${f.added} -${f.removed}`);Each file has path (workspace-relative), status (A added, D deleted, M modified, T type changed), added and removed line counts, and before / after text. When there is no text, omitted says why:
omitted |
Why |
|---|---|
secret |
A secret's file name (.env, keys); snapshots leave those out |
denied |
The session's read rules would not let the agent read it now (a deny or ask rule, an organisation policy) |
binary |
A NUL byte, or not UTF-8 |
too-large |
One side is over 256 KiB |
symlink, submodule |
Not a regular file |
budget |
The response already holds 4 MiB of text |
At most 100 files per turn; more counts the rest. Errors: 404 checkpoint_not_found (unknown in this session), checkpoints_off (no git, or the server set checkpoints: false), checkpoint_gone (retention removed it).
Workspace files
Four routes read and write a session's workspace directly. Paths are workspace-relative and resolved through real paths inside the session's cwd. Files are UTF-8 text up to 512 KiB. The session's own permission rules decide what is readable and writable, exactly as for the agent's read and write tools.
| Operation | Route | What |
|---|---|---|
listFiles |
GET /v1/sessions/{sessionId}/files?path=src |
One directory: {path, entries: [{name, type: file | dir | symlink, size}], truncated}. At most 2000 entries; symlinks are listed, not followed. |
readFile |
GET /v1/sessions/{sessionId}/file?path=src/sum.ts |
{path, content, size} |
writeFile |
PUT /v1/sessions/{sessionId}/file |
Body {path, content}; creates the file when its directory exists. An existing file must also be readable by the session. Answers {path, size}. |
deleteFile |
DELETE /v1/sessions/{sessionId}/file?path=src/old.ts |
Deletes the file |
curl -s "$S/v1/sessions/$SID/files?path=" -H "Authorization: Bearer $TOKEN"
curl -s "$S/v1/sessions/$SID/file?path=src/sum.ts" -H "Authorization: Bearer $TOKEN"
curl -s -X PUT "$S/v1/sessions/$SID/file" -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"path": "notes.md", "content": "# Notes\n"}'These routes are marked x-venom-browser in the spec: they serve the browser IDE, and the Python and TypeScript clients have no methods for them. Call them over plain HTTP.
| Status | Code | Why |
|---|---|---|
| 400 | bad_request, not_a_file, not_text |
Missing or bad path, not a regular file, not UTF-8 |
| 403 | path_outside |
The path leaves the workspace by .., an absolute path or a symlink |
| 403 | path_protected |
Inside .git |
| 403 | read_denied, write_denied |
A deny rule, a secret's name or an organisation policy |
| 404 | session_not_found, file_not_found |
|
| 413 | too_large |
Over 512 KiB |
The browser IDE
GET /v1/ide (getIdePage) serves a self-contained page: the session's files, an editor with a diff of the agent's edits (accept or reject each), the agent chat from the event stream, the output of its shell commands, and its permission questions. Open it in a browser on the same machine:
http://127.0.0.1:8790/v1/ideThe page needs no auth to load and holds nothing. It asks for the server token, keeps it in memory only and sends it as a bearer header, so it has exactly the access any client with the token has. It makes no external request (inline CSS and JS, system fonts) and sends a Content-Security-Policy that allows only its own script and style and requests to this origin. venom serve prints its address at start.
Related pages
- Sessions
- Events:
checkpointandentry_appended - Approvals and questions