> ## Documentation Index
> Fetch the complete documentation index at: https://opensandbox-oc-s-762ac928075c46d2828bcb22.mintlify.site/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.

<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                    | 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"]
  ```
</CodeGroup>

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

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