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)

# Save current filesystem state
cp = sandbox.checkpoint.create(name="baseline")

# Do something destructive
sandbox.exec.run(["bash", "-c", "rm -rf /app/data"])

# Roll back — same sandbox, filesystem rewound
result = sandbox.checkpoint.restore(cp.checkpoint_id)
print(f"Restored in {result.restore_duration_ms}ms")
print("Services restarted:", result.started_services)

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

The restore response has these 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)
  }
}

cp = sandbox.checkpoint.create(name="before-attempt")

for attempt in range(3):
    result = sandbox.exec.run(["python3", "flaky_script.py"])

    if result.ok:
        break

    if attempt < 2:
        # Restore filesystem to the same starting point and retry
        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
  }
}

checkpoints = []

for step in workflow:
    cp = sandbox.checkpoint.create(name=step.name)
    checkpoints.append(cp.checkpoint_id)

    result = sandbox.exec.run(step.cmd)

    if not result.ok:
        if len(checkpoints) >= 2:
            sandbox.checkpoint.restore(checkpoints[-2])
        print(f"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