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.

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.

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

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")

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

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

checkpoint = await sandbox.create_checkpoint("before-migration")
# checkpoint["id"], checkpoint["status"]

oc cp create sb-abc123 --name before-migration

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:

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

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

oc cp create sb-abc123 \
  --name autosave \
  --kind disk_only \
  --retention-policy delete_oldest \
  --retention-max-count 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

const checkpoints = await sandbox.listCheckpoints();

checkpoints = await sandbox.list_checkpoints()

Fork from Checkpoint

Creates a new sandbox from a checkpoint:

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

forked = await Sandbox.create_from_checkpoint(checkpoint_id, timeout=600)

Restore Checkpoint

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

await sandbox.restoreCheckpoint(checkpointId);

await sandbox.restore_checkpoint(checkpoint_id)

Delete Checkpoint

await sandbox.deleteCheckpoint(checkpointId);

await sandbox.delete_checkpoint(checkpoint_id)

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:

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

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

Getting Started

Sandboxes

Browser Sessions

Durable Agent Sessions

Reserved Capacity

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Checkpoint Types

Checkpoints vs Hibernation

What Gets Preserved

API Reference

Create Checkpoint

List Checkpoints

Fork from Checkpoint

Restore Checkpoint

Delete Checkpoint

CheckpointInfo

Example: Parallel Exploration

​Checkpoint Types

​Checkpoints vs Hibernation

​What Gets Preserved

​API Reference

​Create Checkpoint

​List Checkpoints

​Fork from Checkpoint

​Restore Checkpoint

​Delete Checkpoint

​CheckpointInfo

​Example: Parallel Exploration

Checkpoint Types

Checkpoints vs Hibernation

What Gets Preserved

API Reference

Create Checkpoint

List Checkpoints

Fork from Checkpoint

Restore Checkpoint

Delete Checkpoint

CheckpointInfo

Example: Parallel Exploration