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.

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

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

TypeScript

const 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).

List Checkpoints

TypeScript

const checkpoints = await sandbox.listCheckpoints();

Fork from Checkpoint

Creates a new sandbox from a checkpoint:

TypeScript

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

Restore Checkpoint

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

TypeScript

await sandbox.restoreCheckpoint(checkpointId);

Delete Checkpoint

TypeScript

await 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:

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.