Checkpoints & Forking

A checkpoint saves a sandbox’s filesystem so you can start new sandboxes from it later, or fork a running one to branch your work. It captures the sandbox’s root filesystem only — data on mounted volumes is never included. Checkpoints capture files only: processes start fresh and nothing in memory carries over. A checkpoint is usable once it reaches DURABLE. From then on it outlives its source sandbox. Checkpoint storage is billed separately.

Keep the source sandbox alive until the checkpoint is DURABLE. If it’s deleted or hits its timeout first, the checkpoint is lost.

Fork

The quickest way to branch a running sandbox. It checkpoints, waits for DURABLE, and starts a new sandbox from it:

prime sandbox fork sbx_123 --name experiment-branch --yes

The fork inherits the source’s CPU, memory, and timeout unless you pass --cpu-cores, --memory-gb, or --timeout-minutes. Use --wait-timeout (seconds) to cap how long it waits for the checkpoint.

Checkpoint and restore

# 1. Create a checkpoint (prints its ID)
prime sandbox checkpoint create sbx_123

# 2. Poll until its state is DURABLE
prime sandbox checkpoint list sbx_123 --checkpoint-id <checkpoint-id>

# 3. Restore into a new sandbox
prime sandbox checkpoint restore <checkpoint-id> --name restored-workspace --yes

checkpoint = client.checkpoint(sandbox_id)
client.wait_for_checkpoint(checkpoint.id, timeout_seconds=300)

restored = client.create(
    CreateSandboxRequest(name="restored-workspace", checkpoint_id=checkpoint.id)
)
client.wait_for_creation(restored.id)

The image and disk size come from the checkpoint, so leave out docker_image and disk_size_gb in the SDK. Everything else (resources, env vars, timeouts) works as usual; the CLI restore accepts --cpu-cores, --memory-gb, --timeout-minutes, and --team-id. wait_for_checkpoint returns once the checkpoint is DURABLE. It raises RuntimeError if the checkpoint fails and TimeoutError if the wait runs out. A timeout doesn’t mean the checkpoint failed, so check it with get_checkpoint before deleting the source sandbox. list_checkpoints(sandbox_id) lists a sandbox’s checkpoints.

Getting Started

Inference

Model Factory

Community

Compute

Traces

Libraries

Fork

Checkpoint and restore

​Fork

​Checkpoint and restore

Fork

Checkpoint and restore