Session checkpoints
Time-travel debugging with automatic checkpointing, rollback, and pruning
Checkpoints let you undo: the sessions API automatically snapshots a session's state at key moments, so you can roll back to any earlier point and replay from there. Reach for them to recover from a bad turn, experiment safely, or debug by stepping backward through a conversation. They snapshot the same sessions you manage in Manage sessions, and rolling back is one way to recover if a sync goes wrong.
Checkpoints
The runtime saves a snapshot of the session state at each lifecycle event below. Any snapshot can be listed, inspected, or restored.
How Checkpoints Work
Checkpoints are snapshots of SessionState taken at specific lifecycle events. Each checkpoint has a parent pointer, forming a linked history chain.
A checkpoint is not rewritten after it is saved, but it is not permanent either: SupabaseSaver prunes on its own after each write, keeping the newest 50 per session — see Pruning. Treat a checkpoint as a rollback target within that window, not as an archive.
Checkpoint Sources
| Source | Trigger |
|---|---|
manual | Explicitly requested by the user |
message | After an assistant message is finalized |
job_complete | After a computational job finishes |
subagent | After a sub-agent completes or fails |
sync | After a sync operation applies changes |
tool_execution | After a tool call completes |
Lifecycle
List Checkpoints
GET /api/v1/sessions/:sessionId/checkpoints returns { checkpoints, total }, newest first (reference). Each checkpoint carries id, threadId, step, source, parentCheckpointId, toolCallId, jobId and createdAt.
| Query | Default | Meaning |
|---|---|---|
limit | 50 | Page size, capped at 200 |
source | none | Only checkpoints from one source in the table above |
Rollback
Rolling back restores the session to the state captured at a specific checkpoint. All changes made after that checkpoint are discarded.
Rollback is irreversible — the discarded state is not preserved. Note the current newest checkpoint ID before rolling back if you may want to return to it.
POST /api/v1/sessions/:sessionId/rollback takes {"checkpointId": "..."} and returns { success, sessionId, checkpointId, restoredStep, version, updatedAt } (reference). An unknown checkpoint returns 404.
Pruning
Pruning removes old checkpoints to save storage. Keep the N most recent with the saver's prune(sessionId, keepLast):
SupabaseSaver prunes on its own after each write, keeping the newest 50 per session unless you pass maxCheckpointsPerSession.
Storage Backends
| Checkpointer | Environment | Use Case |
|---|---|---|
MemorySaver | Testing | Ephemeral checkpoints (lost on restart) |
IndexedDBSaver | Browser | Offline-first client-side checkpoints |
SupabaseSaver | Server | Persistent PostgreSQL checkpoint storage |
Server Initialization
The server-side execute endpoint initializes the runtime with a SupabaseSaver:
DevTools
Browser DevTools are available for checkpoint inspection:
DevTools are only available when the session React hooks are mounted. Import useHarnessDevTools to enable them.
Database Tables
| Table | Purpose |
|---|---|
harness_checkpoints | Checkpoint data with parent links |
harness_sessions | Session state with version tracking |
harness_errors | Error tracking for debugging |
Read next
- Manage sessions — session management
- Message execution — streaming triggers checkpoints
- Sync protocol — sync creates checkpoints
Was this page helpful?