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

# Create a Sandbox from a Snapshot

> Start a new sandbox from a named snapshot

`POST /v1/agents/runtime`

Pass `snapshot` (name or ID) instead of `template`. The new sandbox is a **new ID**. It is not a resume of the original.

Do not set `template` in the same request.

<CodeGroup>
  ```python Python theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  from gravixlayer import GravixLayer

  client = GravixLayer()  # defaults to cloud="aws", region="us-east-1"

  # After you have a snapshot named "after-warmup"
  sandbox = client.runtime.create(snapshot="after-warmup")

  print(sandbox.runtime_id, sandbox.status)
  print(sandbox.file.read("/workspace/notes.txt").content)

  sandbox.kill()
  ```

  ```typescript TypeScript theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  import { GravixLayer } from 'gravixlayer';

  const client = new GravixLayer(); // defaults to cloud="aws", region="us-east-1"

  // After you have a snapshot named "after-warmup"
  const sandbox = await client.runtime.create({ snapshot: 'after-warmup' });

  console.log(sandbox.runtimeId, sandbox.status);
  console.log((await sandbox.file.read("/workspace/notes.txt")).content);

  await sandbox.kill();
  ```

  ```bash CLI theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # Requires: GRAVIXLAYER_API_KEY, jq

  CHILD=$(gravixlayer runtime create --snapshot after-warmup --wait --output json | jq -r '.runtime_id')
  gravixlayer runtime files cat "$CHILD" /workspace/notes.txt
  gravixlayer runtime kill "$CHILD" -y
  ```

  ```bash cURL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # Requires: GRAVIXLAYER_API_KEY, jq
  API="https://api.gravixlayer.ai/v1"
  AUTH=(-H "Authorization: Bearer $GRAVIXLAYER_API_KEY" -H "Content-Type: application/json")

  CHILD=$(curl -sS -X POST "$API/agents/runtime" "${AUTH[@]}" \
    -d '{
      "snapshot": "after-warmup",
      "cloud": "aws",
      "region": "us-east-1"
    }' | jq -r '.runtime_id')

  for i in $(seq 1 90); do
    STATUS=$(curl -sS "$API/agents/runtime/$CHILD" \
      -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" | jq -r '.status')
    [ "$STATUS" = "running" ] && break
    sleep 2
  done

  curl -sS -X DELETE "$API/agents/runtime/$CHILD" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY"
  ```
</CodeGroup>

You can start many sandboxes from the same snapshot. Each one is independent: stop, files, and timeout on one child do not affect the others or the original sandbox.

## Parameters

Use the same create body as [Create Runtime](/documentation/agentruntime/sandbox-management/create-sandbox) (the sandbox create API), with these rules:

| Parameter  | Type   | Required | Description                                                    |
| ---------- | ------ | -------- | -------------------------------------------------------------- |
| `snapshot` | string | Yes      | Snapshot name or ID                                            |
| `template` | string | No       | **Do not set** when `snapshot` is set                          |
| `cloud`    | string | Yes\*    | Must match the snapshot's cloud (SDK defaults to `aws`)        |
| `region`   | string | Yes\*    | Must match the snapshot's region (SDK defaults to `us-east-1`) |

Timeout, env vars, secrets, and network policies work the same as a template create.

## Cold vs hot restore

| Snapshot kind | New sandbox                                                                    |
| ------------- | ------------------------------------------------------------------------------ |
| `cold`        | Fresh boot. Files from the snapshot are on disk. Processes start from scratch. |
| `hot`         | Continues from saved memory. Processes and in-memory state are back.           |

Hot restore is typically ready in tens of milliseconds. Cold restore waits until the sandbox has booted (up to about 90 seconds).

## Notes

* The snapshot must be `active`. [Deactivated](/documentation/agentruntime/snapshots/activate-deactivate) snapshots cannot create new sandboxes.
* The new sandbox starts in the snapshot's region. If that region has no capacity, the request fails.
* Deleting the snapshot later does not stop sandboxes that already started from it.