Patches

Scripts that run when forking from a checkpoint

A patch is a shell script attached to a checkpoint. Every time a sandbox is forked from that checkpoint, patches run automatically — inject configuration, update dependencies, or customize state without modifying the checkpoint itself.

TypeScript

import { Sandbox } from "@opencomputer/sdk";

// Attach a patch to an existing checkpoint
const result = await Sandbox.createCheckpointPatch(checkpointId, {
  script: 'echo "export API_KEY=$1" >> /root/.bashrc',
  description: "Inject API key at fork time",
});
console.log(result.patch.id, result.patch.sequence);

// Fork — patch runs automatically
const sandbox = await Sandbox.createFromCheckpoint(checkpointId);

API Reference

Create Patch

Patch methods are static on the Sandbox class — they operate on checkpoints, not sandbox instances.

TypeScript

const result = await Sandbox.createCheckpointPatch(checkpointId, {
  script: "apt-get update && apt-get install -y redis-server",
  description: "Install Redis",
});
// result.patch.id, result.patch.sequence

Parameter	Type	Required	Description
checkpointId	string	Yes	Target checkpoint
script	string	Yes	Bash script to execute on fork
description	string	No	Human-readable description

List Patches

TypeScript

const patches = await Sandbox.listCheckpointPatches(checkpointId);
for (const p of patches) {
  console.log(p.sequence, p.description);
}

Delete Patch

TypeScript

await Sandbox.deleteCheckpointPatch(checkpointId, patchId);

When Patches Run

Patches execute when a sandbox is forked from the checkpoint (via Sandbox.createFromCheckpoint() or oc checkpoint spawn). The strategy is always on_wake.

Execution Order

Patches run in creation order (by sequence number). If you create three patches, they execute as patch 1 → patch 2 → patch 3 every time a sandbox is forked.

PatchInfo

Field	Type	Description
id	string	Patch UUID
checkpointId	string	Parent checkpoint
script	string	Bash script content
description	string	Human-readable description
strategy	string	Always "on_wake"
sequence	number	Execution order
createdAt	string	Timestamp

Example: Environment-Specific Forks

Use patches to create different environments from one checkpoint:

// Base checkpoint has the app installed
const cpId = "cp-abc123";

// Patch for staging
await Sandbox.createCheckpointPatch(cpId, {
  script: `
    echo 'DATABASE_URL=postgres://staging-db/app' >> /app/.env
    echo 'LOG_LEVEL=debug' >> /app/.env
  `,
  description: "Staging environment config",
});

// Every fork now gets staging config
const staging = await Sandbox.createFromCheckpoint(cpId);

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