Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.opencomputer.dev/llms.txt

Use this file to discover all available pages before exploring further.

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

CheckpointHibernation
PurposeFork new sandboxes from saved statePause and resume the same sandbox
Original sandboxKeeps runningStopped
Can forkYes — unlimited new sandboxesNo
CountUp to 10 per sandboxOne hibernation state
Use caseParallel testing, branching experimentsCost 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 name must be unique within the sandbox. Status transitions from processing to ready (or failed).

​
List Checkpoints

const checkpoints = await sandbox.listCheckpoints();

​
Fork from Checkpoint

Creates a new sandbox from a checkpoint: 
const forked = await Sandbox.createFromCheckpoint(checkpointId, {
  timeout: 600,
});

​
Restore Checkpoint

Revert a sandbox in-place. All changes since the checkpoint are lost: 
await sandbox.restoreCheckpoint(checkpointId);

​
Delete Checkpoint

await sandbox.deleteCheckpoint(checkpointId);

​
CheckpointInfo

FieldTypeScriptPythonDescription
IDididCheckpoint UUID
Sandbox IDsandboxIdsandboxIDSource sandbox
NamenamenameHuman-readable name
Statusstatusstatusprocessing, ready, or failed
SizesizeBytessizeBytesSnapshot size in bytes
CreatedcreatedAtcreatedAtTimestamp
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.