Checkpoints

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.

Ask AI about this page

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.

typescript

1234567891011121314import { 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" });

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

typescript

12const checkpoint = await sandbox.createCheckpoint("before-migration");
// checkpoint.id, checkpoint.status ("processing" → "ready")

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:

typescript

1234const checkpoint = await sandbox.createCheckpoint("autosave", {
  kind: "disk_only",
  retentionPolicy: { mode: "delete_oldest", maxCount: 100 },
});

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

typescript

1const checkpoints = await sandbox.listCheckpoints();

Fork from Checkpoint

Creates a new sandbox from a checkpoint:

typescript

123const forked = await Sandbox.createFromCheckpoint(checkpointId, {
  timeout: 600,
});

Restore Checkpoint

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

typescript

1await sandbox.restoreCheckpoint(checkpointId);

Delete Checkpoint

typescript

1await sandbox.deleteCheckpoint(checkpointId);

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

The TypeScript SDK returns typed CheckpointInfo objects. Python returns raw dictionaries with the HTTP API field names.

Example: Parallel Exploration

Try multiple approaches from the same starting point:

typescript

1234567891011121314const 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 };
  }),
);

CLI equivalent: oc checkpoint. Full reference: TypeScript SDK · Python SDK · HTTP API.