Skip to main content
A Checkpoint is a fast-resume point for a Session: secret-free metadata over one sandbox snapshot, plus either a harness-owned resume blob or a marker to rebuild from the event log. A Run produces one; a resume or fork consumes one. You mostly need to know three things about them: they expire, expiry has a graceful fallback, and zero-data-retention Workspaces never create them.

​
They expire after 30 days

Every Checkpoint carries an immutable expires_at, defaulting to 30 days after it was created. A Workspace retention policy may shorten that window but never lengthen it. GET /v1/sessions/{id}/checkpoints lists a Session’s Checkpoints as secret-free metadata: the snapshot boundary (through_sequence, through_event_id), the harness and SandboxProfile revisions it was taken against, and the timestamps. It never returns snapshot contents.

​
Expiry can fall back to a retained log

The event log is the durable truth; the sandbox snapshot is an optimization on top of it. Checkpoint expiry alone therefore loses the fast path to the disk, not the retained log. Independent retention expiry, subject erasure, or zero-data-retention omission can still make content positions unreadable and prevent an exact reconstruction.
  • An ordinary later Run does not name a Checkpoint. If the latest snapshot expired while its conversation is still readable, its Runner claim says event_log_rebuild with reason checkpoint_expired; the fresh sandbox receives the retained conversation but none of the old disk.
  • Explicitly forking against an expired Checkpoint returns 409 runtime.checkpoint_expired. It does not silently reinterpret the named snapshot as a log-only fork.
  • If you retained the Checkpoint’s through_event_id and that complete prefix remains readable, you can explicitly request an at_event rebuild, which restores conversational state only. The sandbox disk is gone with the snapshot. An incomplete prefix instead returns 409 runtime.session_history_unavailable.
The distinction to hold onto: conversation can be reconstructed while its selected log prefix remains readable; the sandbox disk is only recoverable while the snapshot lives. Anything an agent must not lose belongs in Memory, a Project revision, or an Outcome deliverable, not in un-checkpointed sandbox scratch.
A zero-data-retention Workspace creates neither a Checkpoint nor a snapshot, so GET /checkpoints there always returns an empty list and there is no checkpoint selector to consume.
Checkpoint listing and all three Session-fork selectors ship. A checkpoint fork is available only while its snapshot is live and a live Runner advertises the exact execution target with snapshot-clone support: the exact settling Runner when the provider keeps snapshot bytes on that Runner’s host, or any compatibly enrolled Runner when the provider retains them platform-side. The target is not addressable until the clone and event-history transfer are both adopted.

​
Next steps

Sessions and runs

How a Run settles and what the event log preserves.

Memory

Where durable knowledge lives, safe from snapshot expiry.