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

# Restore Sandbox

> Restore a sandbox from a snapshot, potentially on a different worker.

Performs a cross-worker sandbox restore. Resolves the snapshot to restore from
(either an explicitly named `snapshot_id` or the best available), picks an
eligible orchestrator node — always excluding the originating node — forwards
the restore to that orchestrator, and updates sandbox-manager state with the
new node assignment.

Unlike [resume](/api-reference/sandbox/resume), restore works on sandboxes in
any state as long as at least one snapshot exists, and always lands the sandbox
on a fresh worker.

## Path Parameters

<ParamField path="sandbox_id" type="string" required>
  The sandbox identifier. Format: `sbx-<8 chars>`.
</ParamField>

## Query Parameters

<ParamField query="snapshot_id" type="string">
  Optional specific snapshot to restore from. If omitted, the best available
  snapshot is selected (preference: `pause` → `periodic` → `manual`).
</ParamField>

## Response

Returns the orchestrator's restore response (passed through), including the
new `guest_ip` and `envd_port` for the restored VM.

## Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://api.declaw.ai/sandboxes/sbx-a1b2c3d4/restore?snapshot_id=snap-xyz" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  from declaw import Sandbox

  sbx = Sandbox.restore(
      "sbx-a1b2c3d4",
      snapshot_id="snap-xyz",
      api_key="YOUR_API_KEY",
      domain="api.declaw.ai",
  )
  sbx.commands.run("echo restored")
  ```

  ```typescript TypeScript theme={null}
  import { Sandbox } from "@declaw/sdk";

  const sbx = await Sandbox.restore("sbx-a1b2c3d4", {
    snapshotId: "snap-xyz",
    apiKey: "YOUR_API_KEY",
    domain: "api.declaw.ai",
  });
  ```
</CodeGroup>

## Error Responses

| Status | Cause                                       |
| ------ | ------------------------------------------- |
| `401`  | Missing or invalid API key                  |
| `404`  | Sandbox not found, or no snapshot available |
| `502`  | Orchestrator unreachable or restore failed  |
| `503`  | No eligible orchestrator node available     |