Skip to content
[iris]

Checkpoints

What is a Checkpoint?

A checkpoint captures the filesystem state of a sandbox at a point in time — all files and directories as they exist on disk.

The sandbox keeps running after a checkpoint is created — it is non-blocking.

To roll a sandbox back to a checkpoint, see Checkpoint Restore.

Creating Checkpoints

const cp = await sandbox.checkpoint.create()


console.log(cp.checkpoint_id)    // "abc123..."
console.log(cp.size_bytes)       // 134217728
console.log(cp.copy_duration_ms) // how long the checkpoint took
console.log(cp.ok)               // true on success

Named Checkpoints

const cp = await sandbox.checkpoint.create({ name: 'after-training' })

name string — Optional human-readable name for the checkpoint.

How It Works

Iris uses copy-on-write filesystem snapshots:

  1. A snapshot reference of the current disk blocks is created (near-instant)
  2. The sandbox continues running and writing normally
  3. On write, only the modified blocks are copied — unmodified blocks are shared
  4. The snapshot preserves the filesystem as it was at checkpoint time

This means checkpoints are:

  • Instant — No copying at checkpoint time
  • Space-efficient — Only blocks changed after the checkpoint use additional storage
  • Non-blocking — Sandbox continues running immediately

Listing Checkpoints

const { checkpoints } = await sandbox.checkpoint.list()


for (const cp of checkpoints) {
  console.log(`${cp.name ?? cp.id}: ${cp.size_human} (${cp.created_at})`)
}

CheckpointInfo fields: id, name, created_at, size_bytes, size_human.

Waiting for a Checkpoint

Checkpoint creation is asynchronous. checkpoint.create() returns immediately; use checkpoint.wait() to block until a specific checkpoint is fully written:

const cp = await sandbox.checkpoint.create({ name: 'big-state' })
await sandbox.checkpoint.wait({ checkpoint_id: cp.checkpoint_id })
// Now safe to fork — checkpoint is fully flushed

Deleting Checkpoints

await sandbox.checkpoint.delete(cp.checkpoint_id)

Best Practices

Checkpoint after setup

Create a checkpoint after installing dependencies and seeding data. Fork from it to skip setup on every run.

Name your checkpoints

Use descriptive names like after-deps-installed or epoch-10 for easy identification.

Clean up old checkpoints

Delete checkpoints you no longer need to keep storage costs down.