Snapshots - Run Cloud

A snapshot captures a sandbox’s filesystem so you can restore it later. Do the expensive setup once (install dependencies, clone a repository, warm a cache), snapshot it, and start every later sandbox from that point instead of repeating the work.

Create a snapshot

runcloud sandbox exec sbx_abc123 "npm ci"
runcloud sandbox snapshot create sbx_abc123 --label deps-installed --json

await cloud.sandboxes.exec(sandbox.id, "npm ci");

const snapshot = await cloud.sandboxes.snapshot(sandbox.id, {
  label: "deps-installed",
});

console.log(snapshot.id);

Restore

Restoring produces a new sandbox with its own id. The snapshot is not consumed, so one snapshot can fan out into as many sandboxes as you need, which is what makes this useful for running a test matrix in parallel.

runcloud sandbox restore snap_abc123 --json

const restored = await cloud.snapshots.restore(snapshot.id);

await cloud.sandboxes.exec(restored.id, "npm test");
await cloud.sandboxes.destroy(restored.id);

Fanning one snapshot out across several sandboxes:

const shards = await Promise.all(
  [1, 2, 3, 4].map(() => cloud.snapshots.restore(snapshot.id)),
);

const results = await Promise.all(
  shards.map((s, i) =>
    cloud.sandboxes.exec(s.id, `npm test -- --shard=${i + 1}/4`),
  ),
);

await Promise.all(shards.map((s) => cloud.sandboxes.destroy(s.id)));

Restored sandboxes count against the same 100-concurrent-sandbox limit as any other, so destroy them when the work finishes.

List and delete

runcloud sandbox snapshot list --json
runcloud sandbox snapshot list --sandbox sbx_abc123 --json
runcloud sandbox snapshot rm snap_abc123

const snapshots = await cloud.snapshots.list();
await cloud.snapshots.delete(snapshot.id);

Snapshot storage is not metered today, so keeping one costs nothing. Delete the ones you no longer need rather than relying on that. A restore forks a new sandbox, which counts against your concurrency limit and is billed for the CPU and memory it reserves.