Checkpoint Restore

What is Checkpoint Restore?

sandbox.checkpoint.restore(checkpointId) rewinds the sandbox’s filesystem to the state captured in a named checkpoint. The same sandbox object is reused — no new sandbox is created.

To create a checkpoint to restore from, see Checkpoints.

// Save current filesystem state
const cp = await sandbox.checkpoint.create({ name: 'baseline' })

// Do something destructive
await sandbox.exec.run('rm -rf /app/data')

// Roll back — same sandbox, filesystem rewound
const result = await sandbox.checkpoint.restore(cp.checkpoint_id)
console.log(`Restored in ${result.restore_duration_ms}ms`)
console.log('Services restarted:', result.started_services)

Caution

Checkpoint restore rolls back the filesystem only. In-memory state is not preserved — running processes are stopped and restarted from their on-disk state at the time of the checkpoint. Network connections are not restored.

Response Fields

RestoreResponse fields:

Field	Type	Description
ok	boolean	true if restore completed without errors
restore_duration_ms	number	How long the restore took
started_services	string[]	Services successfully restarted
stopped_services	string[]	Services that were stopped
failed_services	string[]	Services that failed to restart

Retry Loops

Restore is useful when you need to retry an operation from a known-good filesystem state:

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

for (let attempt = 0; attempt < 3; attempt++) {
  const result = await sandbox.exec.run('python3 flaky_script.py')

  if (result.ok) break

  if (attempt < 2) {
    // Restore filesystem to the same starting point and retry
    await sandbox.checkpoint.restore(cp.checkpoint_id)
  }
}

Multi-Step Rollback

Checkpoint at each successful step and restore to the last good state on failure:

const checkpoints: string[] = []

for (const step of workflow) {
  const cp = await sandbox.checkpoint.create({ name: step.name })
  checkpoints.push(cp.checkpoint_id)

  const result = await sandbox.exec.run(step.code)

  if (!result.ok) {
    const lastGood = checkpoints[checkpoints.length - 2]
    if (lastGood) await sandbox.checkpoint.restore(lastGood)
    console.error(`Step ${step.name} failed:`, result.stderr)
    break
  }
}

Fork vs Restore — When to Use Each

	fork()	checkpoint.restore(id)
Result	New independent sandbox	Same sandbox, filesystem rewound
Original sandbox	Keeps running unchanged	Modified in-place
Parallelism	Multiple branches at once	Sequential — one restore at a time
Use case	Parallel experiments, test isolation	Retry loops, sequential rollback
Scope	Filesystem copy-on-write	Filesystem rollback
Memory	Not captured	Not captured