> ## Documentation Index
> Fetch the complete documentation index at: https://docs.run.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Snapshots

> Capture a prepared sandbox and restore it as many times as you need.

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

<CodeGroup>
  ```bash Bash theme={null}
  runcloud sandbox exec sbx_abc123 "npm ci"
  runcloud sandbox snapshot create sbx_abc123 --label deps-installed --json
  ```

  ```typescript TypeScript theme={null}
  await cloud.sandboxes.exec(sandbox.id, "npm ci");

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

  console.log(snapshot.id);
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash Bash theme={null}
  runcloud sandbox restore snap_abc123 --json
  ```

  ```typescript TypeScript theme={null}
  const restored = await cloud.snapshots.restore(snapshot.id);

  await cloud.sandboxes.exec(restored.id, "npm test");
  await cloud.sandboxes.destroy(restored.id);
  ```
</CodeGroup>

Fanning one snapshot out across several sandboxes:

```ts theme={null}
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

<CodeGroup>
  ```bash Bash theme={null}
  runcloud sandbox snapshot list --json
  runcloud sandbox snapshot list --sandbox sbx_abc123 --json
  runcloud sandbox snapshot rm snap_abc123
  ```

  ```typescript TypeScript theme={null}
  const snapshots = await cloud.snapshots.list();
  await cloud.snapshots.delete(snapshot.id);
  ```
</CodeGroup>

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.