Snapshots

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

Getting Started

Linux Sandboxes

CI

iOS

Android

Billing

Agents

Create a snapshot

Restore

List and delete

​Create a snapshot

​Restore

​List and delete

Create a snapshot

Restore

List and delete