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.

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

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

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

Reserved Capacity

Agent SDK

Hosted Agents

CLI

Guides

TypeScript SDK

Python SDK

CLI Reference

API Reference

Resources

Checkpoints vs Hibernation

What Gets Preserved

API Reference

Create Checkpoint

List Checkpoints

Fork from Checkpoint

Restore Checkpoint

Delete Checkpoint

CheckpointInfo

Example: Parallel Exploration

​Checkpoints vs Hibernation

​What Gets Preserved

​API Reference

​Create Checkpoint

​List Checkpoints

​Fork from Checkpoint

​Restore Checkpoint

​Delete Checkpoint

​CheckpointInfo

​Example: Parallel Exploration

Checkpoints vs Hibernation

What Gets Preserved

API Reference

Create Checkpoint

List Checkpoints

Fork from Checkpoint

Restore Checkpoint

Delete Checkpoint

CheckpointInfo

Example: Parallel Exploration