---
title: Files, checkpoints and the browser IDE
description: 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.
section: server-api
order: 40
audience: [builder, agent]
sources: [packages/harness-server/openapi.yaml, packages/harness-server/src/files.ts, packages/harness-server/src/ide-page.ts, docs/web-ide.md]
features: [server-api.sessions-checkpoints, server-api.sessions-changes, server-api.sessions-files, server-api.sessions-file, server-api.ide]
---

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

`GET /v1/sessions/{sessionId}/checkpoints` (`listCheckpoints`) lists the session's turn checkpoints, oldest first:

```json
{
  "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 {#changes}

`GET /v1/sessions/{sessionId}/changes?turn=<entryId>` (`getChanges`) returns each file that turn changed, with its text before and after:

```bash
curl -s "$S/v1/sessions/$SID/changes?turn=e7c1" -H "Authorization: Bearer $TOKEN"
```

```python
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']}")
```

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

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

```text
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.

## Related pages

- [Sessions](/docs/server-api/sessions.md)
- [Events](/docs/server-api/events.md): `checkpoint` and `entry_appended`
- [Approvals and questions](/docs/server-api/approvals-and-questions.md)
