> ## Documentation Index
> Fetch the complete documentation index at: https://docs.primeintellect.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkpoints & Forking

> Save a sandbox's filesystem, restore it, or branch it

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](./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](./overview#pricing).

> [!WARNING]
>
> 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:

```bash theme={null}
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

```bash CLI theme={null}
# 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
```

```python Python theme={null}
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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.