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

# Snapshots and forking

> Create point-in-time snapshots of sandboxes, roll them back to a previous checkpoint, and fork them into new sandboxes.

<Note>
  This feature is currently in private preview and is not recommended for production use.
</Note>

Snapshots capture the current state of a sandbox at a point in time. Use snapshots to checkpoint sandbox state to allow rollbacks after making changes, or as the basis for forking a sandbox into a new sandbox.

## Create a snapshot

Create a snapshot of an existing sandbox. The snapshot captures the filesystem, running processes, and memory state.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { SandboxInstance } from "@blaxel/core";

  const sandbox = await SandboxInstance.get("my-sandbox");
  const snapshot = await sandbox.snapshot("before-migration");
  ```

  ```python Python theme={null}
  from blaxel.core import SandboxInstance

  sandbox = await SandboxInstance.get("my-sandbox")
  snapshot = await sandbox.snapshot("before-migration")
  ```

  ```bash HTTP API theme={null}
  curl -X POST https://api.blaxel.ai/v0/sandboxes/my-sandbox/snapshots \
    -H "Authorization: Bearer $BL_API_KEY" \
    -H "X-Blaxel-Workspace: my-workspace" \
    -H "Content-Type: application/json" \
    -d '{ "name": "before-migration" }'
  ```
</CodeGroup>

## List snapshots

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { SandboxInstance } from "@blaxel/core";

  const sandbox = await SandboxInstance.get("my-sandbox");
  const snapshots = await sandbox.listSnapshots();
  ```

  ```python Python theme={null}
  from blaxel.core import SandboxInstance

  sandbox = await SandboxInstance.get("my-sandbox")
  snapshots = await sandbox.list_snapshots()
  ```

  ```bash HTTP API theme={null}
  curl https://api.blaxel.ai/v0/sandboxes/my-sandbox/snapshots \
    -H "Authorization: Bearer $BL_API_KEY" \
    -H "X-Blaxel-Workspace: my-workspace"
  ```
</CodeGroup>

## Delete a snapshot

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { SandboxInstance } from "@blaxel/core";

  const sandbox = await SandboxInstance.get("my-sandbox");
  await sandbox.deleteSnapshot("snap_abc123");
  ```

  ```python Python theme={null}
  from blaxel.core import SandboxInstance

  sandbox = await SandboxInstance.get("my-sandbox")
  await sandbox.delete_snapshot("snap_abc123")
  ```

  ```bash HTTP API theme={null}
  curl -X DELETE https://api.blaxel.ai/v0/sandboxes/my-sandbox/snapshots/snap_abc123 \
    -H "Authorization: Bearer $BL_API_KEY" \
    -H "X-Blaxel-Workspace: my-workspace"
  ```
</CodeGroup>

## Restore a sandbox to a snapshot

Restoring rolls a sandbox back to one of its own snapshots, in place. The sandbox keeps its name, its URLs, its previews, and its configuration: only the instance behind it is torn down and rebuilt from the snapshot, on the same machine the snapshot was taken on.

<Warning>
  Everything the sandbox wrote after the snapshot was taken is lost: files, running processes, and memory state. Take a new snapshot first if you want to be able to come back to the current state.
</Warning>

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { SandboxInstance } from "@blaxel/core";

  const sandbox = await SandboxInstance.get("my-sandbox");
  await sandbox.restore("snap_abc123");
  ```

  ```python Python theme={null}
  from blaxel.core import SandboxInstance

  sandbox = await SandboxInstance.get("my-sandbox")
  await sandbox.restore("snap_abc123")
  ```

  ```bash HTTP API theme={null}
  curl -X POST https://api.blaxel.ai/v0/sandboxes/my-sandbox/snapshots/snap_abc123/restore \
    -H "Authorization: Bearer $BL_API_KEY" \
    -H "X-Blaxel-Workspace: my-workspace"
  ```
</CodeGroup>

The restore returns as soon as it is accepted, without waiting for the sandbox to be back up. The sandbox answers again once its instance has been rebuilt, so retry your first calls while it resumes.

Only a snapshot of that same sandbox can be restored, and only once it is `ready`. To roll back onto a *different* sandbox, [fork from the snapshot](#fork-from-a-snapshot) instead.

You can also restore from the Blaxel console: open your sandbox, go to the **Snapshots** tab, and use the **Restore** action on the snapshot you want to go back to.

## Fork a sandbox

Forking creates a new sandbox from an existing one, forking its entire memory state (files + running processes). The fork inherits the source sandbox's image, memory configuration, environment variables, and port settings.

Calling `fork()` automatically snapshots the source sandbox's current state and forks from it. You don't need to create a snapshot first.

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { SandboxInstance } from "@blaxel/core";

  const sandbox = await SandboxInstance.get("my-sandbox");
  const result = await sandbox.fork("my-sandbox-copy");
  ```

  ```python Python theme={null}
  from blaxel.core import SandboxInstance

  sandbox = await SandboxInstance.get("my-sandbox")
  result = await sandbox.fork("my-sandbox-copy")
  ```

  ```bash CLI theme={null}
  bl fork sbx/my-sandbox sbx/my-sandbox-copy
  ```

  ```bash HTTP API theme={null}
  curl -X POST https://api.blaxel.ai/v0/sandboxes/my-sandbox/fork \
    -H "Authorization: Bearer $BL_API_KEY" \
    -H "X-Blaxel-Workspace: my-workspace" \
    -H "Content-Type: application/json" \
    -d '{
      "targetType": "sandbox",
      "targetName": "my-sandbox-copy"
    }'
  ```
</CodeGroup>

### Fork from a snapshot

To create a sandbox from a snapshot you took earlier, pass its `snapshotId`. The fork is created from that snapshot instead of the source sandbox's current state:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { SandboxInstance } from "@blaxel/core";

  const sandbox = await SandboxInstance.get("my-sandbox");
  const result = await sandbox.fork("my-sandbox-copy", {
    targetType: "sandbox",
    snapshotId: "snap_abc123",
  });
  ```

  ```python Python theme={null}
  from blaxel.core import SandboxInstance

  sandbox = await SandboxInstance.get("my-sandbox")
  result = await sandbox.fork(
      "my-sandbox-copy",
      target_type="sandbox",
      snapshot_id="snap_abc123",
  )
  ```

  ```bash HTTP API theme={null}
  curl -X POST https://api.blaxel.ai/v0/sandboxes/my-sandbox/fork \
    -H "Authorization: Bearer $BL_API_KEY" \
    -H "X-Blaxel-Workspace: my-workspace" \
    -H "Content-Type: application/json" \
    -d '{
      "targetType": "sandbox",
      "targetName": "my-sandbox-copy",
      "snapshotId": "snap_abc123"
    }'
  ```
</CodeGroup>

## Fork request parameters

| Parameter    | Type    | Description                                            |
| ------------ | ------- | ------------------------------------------------------ |
| `targetType` | string  | Target resource type: `sandbox`                        |
| `targetName` | string  | Name of the sandbox to create                          |
| `port`       | integer | Port to expose                                         |
| `snapshotId` | string  | Fork from a specific snapshot instead of current state |

<CardGroup cols={1}>
  <Card title="Sandbox overview" icon="cube" href="/Sandboxes/Overview">
    Learn more about sandbox lifecycle and configuration.
  </Card>
</CardGroup>