> Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

---
title: "Checkpoints"
description: "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.

<Tabs items={["TypeScript", "Python"]}>
  <Tab title="TypeScript">
    ```typescript
    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" });
    ```
  </Tab>

  <Tab title="Python">
    ```python
    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")
    ```
  </Tab>
</Tabs>

## 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

<Tabs items={["TypeScript", "Python", "CLI"]}>
  <Tab title="TypeScript">
    ```typescript
    const checkpoint = await sandbox.createCheckpoint("before-migration");
    // checkpoint.id, checkpoint.status ("processing" → "ready")
    ```
  </Tab>

  <Tab title="Python">
    ```python
    checkpoint = await sandbox.create_checkpoint("before-migration")
    # checkpoint["id"], checkpoint["status"]
    ```
  </Tab>

  <Tab title="CLI">
    ```bash
    oc cp create sb-abc123 --name before-migration
    ```
  </Tab>
</Tabs>

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:

<Tabs items={["TypeScript", "Python", "CLI"]}>
  <Tab title="TypeScript">
    ```typescript
    const checkpoint = await sandbox.createCheckpoint("autosave", {
      kind: "disk_only",
      retentionPolicy: { mode: "delete_oldest", maxCount: 100 },
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python
    checkpoint = await sandbox.create_checkpoint(
        "autosave",
        kind="disk_only",
        retention_policy={"mode": "delete_oldest", "maxCount": 100},
    )
    ```
  </Tab>

  <Tab title="CLI">
    ```bash
    oc cp create sb-abc123 \
      --name autosave \
      --kind disk_only \
      --retention-policy delete_oldest \
      --retention-max-count 100
    ```
  </Tab>
</Tabs>

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

<Tabs items={["TypeScript", "Python"]}>
  <Tab title="TypeScript">
    ```typescript
    const checkpoints = await sandbox.listCheckpoints();
    ```
  </Tab>

  <Tab title="Python">
    ```python
    checkpoints = await sandbox.list_checkpoints()
    ```
  </Tab>
</Tabs>

### Fork from Checkpoint

Creates a new sandbox from a checkpoint:

<Tabs items={["TypeScript", "Python"]}>
  <Tab title="TypeScript">
    ```typescript
    const forked = await Sandbox.createFromCheckpoint(checkpointId, {
      timeout: 600,
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python
    forked = await Sandbox.create_from_checkpoint(checkpoint_id, timeout=600)
    ```
  </Tab>
</Tabs>

### Restore Checkpoint

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

<Tabs items={["TypeScript", "Python"]}>
  <Tab title="TypeScript">
    ```typescript
    await sandbox.restoreCheckpoint(checkpointId);
    ```
  </Tab>

  <Tab title="Python">
    ```python
    await sandbox.restore_checkpoint(checkpoint_id)
    ```
  </Tab>
</Tabs>

### Delete Checkpoint

<Tabs items={["TypeScript", "Python"]}>
  <Tab title="TypeScript">
    ```typescript
    await sandbox.deleteCheckpoint(checkpointId);
    ```
  </Tab>

  <Tab title="Python">
    ```python
    await sandbox.delete_checkpoint(checkpoint_id)
    ```
  </Tab>
</Tabs>

## 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
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>