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

# Snapshots and pausing

Pause and resume a sandbox in place, save its memory and disk as a snapshot, and start new sandboxes from the snapshot with fresh identities.

## Pause and resume

`POST /v1/sandboxes/{sandbox_id}/pause` freezes the sandbox's vCPUs and keeps its memory and disk on the node. `POST /v1/sandboxes/{sandbox_id}/resume` continues exactly where it stopped: processes carry on, open files stay open, and the guest clock is corrected. Pausing a paused sandbox, or resuming a running one, returns it unchanged.

```bash
curl -s -X POST "https://beta-api.b3os.org/v1/sandboxes/$SBX/pause" -H "Authorization: Bearer $B3OS_API_KEY"
curl -s -X POST "https://beta-api.b3os.org/v1/sandboxes/$SBX/resume" -H "Authorization: Bearer $B3OS_API_KEY"
```

A paused sandbox bills no CPU time and still expires at `expires_at`. Whether it bills memory while paused is still being settled for the beta; the sandbox's `usage` shows what it was charged. Create a sandbox with `on_idle: "pause"` to have it pause instead of stopping when its time runs out; extend the timeout, then resume it.

The target for pause and for resume is 1 ms each; see [benchmarks](/benchmarks).

## Save a snapshot

`POST /v1/sandboxes/{sandbox_id}/snapshot` saves the sandbox's memory and disk. The sandbox pauses for the copy, then keeps running:

**curl**

```bash
    curl -s -X POST "https://beta-api.b3os.org/v1/sandboxes/$SBX/snapshot" \
      -H "Authorization: Bearer $B3OS_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name": "deps-installed"}'
    ```
  **TypeScript**

```ts
    const snapshot = await b3os.sandboxes.createSnapshot(sbx, { name: "deps-installed" });
    console.log(snapshot.id, snapshot.status, snapshot.size_bytes);
    ```
  **Python**

```python
    snapshot = b3os.sandboxes.create_snapshot(sbx, {"name": "deps-installed"})
    print(snapshot["id"], snapshot["status"], snapshot["size_bytes"])
    ```
  **MCP**

```text
    Install the project's dependencies in my sandbox with npm ci.
    ```

    The agent runs the install with `sandbox_exec`. The MCP server has no snapshot tool, so take the snapshot from code, or with `b3os api POST /v1/sandboxes/$SBX/snapshot --data '{"name": "deps-installed"}'`.

A snapshot keeps the template, sizes and contents of its sandbox. Its `status` is `creating`, then `ready` (or `failed`; the sandbox keeps running unchanged and you can retry). Snapshots are kept for 7 days in the beta.

## Start from a snapshot

Pass the snapshot instead of a template:

```bash
curl -s https://beta-api.b3os.org/v1/sandboxes \
  -H "Authorization: Bearer $B3OS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"snapshot": "snap_01m5t5mnvax7tp9peav8jajw3y"}'
```

The new sandbox starts with the snapshot's processes and files in memory, already running. Each sandbox restored from a snapshot gets a fresh identity (new entropy, machine ID and clock), so two of them never share random state, and the same snapshot can start many sandboxes. Use this to install dependencies once and start every later sandbox warm.

`GET /v1/sandboxes/snapshots` lists your snapshots, `GET /v1/sandboxes/snapshots/{snapshot_id}` returns one, and `DELETE` removes one; sandboxes already restored from it keep running.

## Templates are snapshots too

Templates (`base`, `code-interpreter`, `agent`) are snapshots B3OS prepares and keeps resident on the node. Creating a sandbox from a template claims one of a pool of microVMs already restored from it, which is why creation does not wait for a boot. `GET /v1/sandboxes/templates` lists them.

## Fork

Forking a running sandbox into several copies that share memory and disk copy-on-write is planned for later in the beta. Until a node serves it, `POST /v1/sandboxes/{sandbox_id}/fork` answers [`501 not_implemented`](/errors#not_implemented). Sandboxes meant to be forked are created with `forkable: true`.