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

# Checkpoints

> Snapshot and fork sandbox state

A checkpoint is a named snapshot of a running sandbox. Fork new sandboxes from it to start from a known-good environment — like git branches for VMs.

## Checkpoint Types

OpenComputer supports two checkpoint modes:

| Type                 | Preserves                       | Use when                                                                                                                                                                                        |
| -------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Full checkpoint      | Disk, memory, and CPU state     | You want the fastest fork or restore path from an exact running VM state. This is best for templates, important milestones, and branches you expect to fork often.                              |
| Disk-only checkpoint | Rootfs and workspace disk state | You want lightweight, frequent snapshots of files, installed packages, and workspace changes. Forks boot from the saved disks, so they are cheaper to keep but may take longer to become ready. |

Full checkpoints are the default. Use `kind: "disk_only"` when creating autosaves or high-frequency checkpoints where disk state is enough.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { Sandbox } from "@opencomputer/sdk";

  const sandbox = await Sandbox.create();
  await sandbox.exec.run("npm install && npm run build", { cwd: "/app" });

  // Checkpoint after setup
  const cp = await sandbox.createCheckpoint("after-build");

  // Fork two independent sandboxes
  const a = await Sandbox.createFromCheckpoint(cp.id);
  const b = await Sandbox.createFromCheckpoint(cp.id);

  await a.exec.run("npm run test:unit", { cwd: "/app" });
  await b.exec.run("npm run test:e2e", { cwd: "/app" });
  ```

  ```python Python theme={null}
  from opencomputer import Sandbox

  sandbox = await Sandbox.create()
  await sandbox.exec.run("npm install && npm run build", cwd="/app")

  cp = await sandbox.create_checkpoint("after-build")

  a = await Sandbox.create_from_checkpoint(cp["id"])
  b = await Sandbox.create_from_checkpoint(cp["id"])

  await a.exec.run("npm run test:unit", cwd="/app")
  await b.exec.run("npm run test:e2e", cwd="/app")
  ```
</CodeGroup>

## Checkpoints vs Hibernation

|                  | Checkpoint                                                    | Hibernation                           |
| ---------------- | ------------------------------------------------------------- | ------------------------------------- |
| Purpose          | Fork new sandboxes from saved state                           | Pause and resume the **same** sandbox |
| Original sandbox | Keeps running                                                 | Stopped                               |
| Can fork         | Yes — unlimited new sandboxes                                 | No                                    |
| Count            | Up to 10 per sandbox, with optional oldest-checkpoint cleanup | One hibernation state                 |
| Use case         | Parallel testing, branching experiments                       | Cost savings, idle timeout            |

## What Gets Preserved

Checkpoints capture the filesystem and installed state. Forked sandboxes start with a fresh boot from that disk state — the platform attempts warm restore when possible, but may fall back to a cold boot. Don't assume running processes carry over.

## API Reference

### Create Checkpoint

<CodeGroup>
  ```typescript TypeScript theme={null}
  const checkpoint = await sandbox.createCheckpoint("before-migration");
  // checkpoint.id, checkpoint.status ("processing" → "ready")
  ```

  ```python Python theme={null}
  checkpoint = await sandbox.create_checkpoint("before-migration")
  # checkpoint["id"], checkpoint["status"]
  ```

  ```bash CLI theme={null}
  oc cp create sb-abc123 --name before-migration
  ```
</CodeGroup>

Checkpoint name must be unique within the sandbox. Status transitions from `processing` to `ready` (or `failed`).

Each sandbox can have up to 10 full checkpoints and up to 100 disk-only checkpoints. To create a new checkpoint without failing at the limit, pass a retention policy that deletes the oldest eligible checkpoint of the same type first:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const checkpoint = await sandbox.createCheckpoint("autosave", {
    kind: "disk_only",
    retentionPolicy: { mode: "delete_oldest", maxCount: 100 },
  });
  ```

  ```python Python theme={null}
  checkpoint = await sandbox.create_checkpoint(
      "autosave",
      kind="disk_only",
      retention_policy={"mode": "delete_oldest", "maxCount": 100},
  )
  ```

  ```bash CLI theme={null}
  oc cp create sb-abc123 \
    --name autosave \
    --kind disk_only \
    --retention-policy delete_oldest \
    --retention-max-count 100
  ```
</CodeGroup>

Retention skips checkpoints that are public, have patches, or are still referenced by forked sandboxes. If no eligible checkpoint of the requested type can be deleted, creation fails instead of deleting protected state.

### List Checkpoints

<CodeGroup>
  ```typescript TypeScript theme={null}
  const checkpoints = await sandbox.listCheckpoints();
  ```

  ```python Python theme={null}
  checkpoints = await sandbox.list_checkpoints()
  ```
</CodeGroup>

### Fork from Checkpoint

Creates a new sandbox from a checkpoint:

<CodeGroup>
  ```typescript TypeScript theme={null}
  const forked = await Sandbox.createFromCheckpoint(checkpointId, {
    timeout: 600,
  });
  ```

  ```python Python theme={null}
  forked = await Sandbox.create_from_checkpoint(checkpoint_id, timeout=600)
  ```
</CodeGroup>

### Restore Checkpoint

Revert a sandbox in-place. All changes since the checkpoint are lost:

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.restoreCheckpoint(checkpointId);
  ```

  ```python Python theme={null}
  await sandbox.restore_checkpoint(checkpoint_id)
  ```
</CodeGroup>

### Delete Checkpoint

<CodeGroup>
  ```typescript TypeScript theme={null}
  await sandbox.deleteCheckpoint(checkpointId);
  ```

  ```python Python theme={null}
  await sandbox.delete_checkpoint(checkpoint_id)
  ```
</CodeGroup>

## CheckpointInfo

| Field      | TypeScript  | Python      | Description                        |
| ---------- | ----------- | ----------- | ---------------------------------- |
| ID         | `id`        | `id`        | Checkpoint UUID                    |
| Sandbox ID | `sandboxId` | `sandboxID` | Source sandbox                     |
| Name       | `name`      | `name`      | Human-readable name                |
| Status     | `status`    | `status`    | `processing`, `ready`, or `failed` |
| Size       | `sizeBytes` | `sizeBytes` | Snapshot size in bytes             |
| Created    | `createdAt` | `createdAt` | Timestamp                          |

<Note>
  The TypeScript SDK returns typed `CheckpointInfo` objects. Python returns raw dictionaries with the HTTP API field names.
</Note>

## Example: Parallel Exploration

Try multiple approaches from the same starting point:

```typescript theme={null}
const sandbox = await Sandbox.create();
await sandbox.exec.run("git clone https://github.com/user/repo /app");
const cp = await sandbox.createCheckpoint("fresh-clone");

// Try three different migration strategies in parallel
const strategies = ["--strategy=ours", "--strategy=theirs", "--strategy=recursive"];
const results = await Promise.all(
  strategies.map(async (strategy) => {
    const fork = await Sandbox.createFromCheckpoint(cp.id);
    const result = await fork.exec.run(`cd /app && git merge origin/main ${strategy}`);
    await fork.kill();
    return { strategy, exitCode: result.exitCode };
  }),
);
```

<Tip>
  CLI equivalent: [`oc checkpoint`](/cli/checkpoint). Full reference: [TypeScript SDK](/reference/typescript-sdk#sandbox) · [Python SDK](/reference/python-sdk#sandbox) · [HTTP API](/reference/api#checkpoints).
</Tip>