Skip to content
Docs menu

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.

View .md

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

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