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

> Capture a running sandbox into a named snapshot

`POST /v1/agents/snapshots`

Capture the current state of a **running** or **paused** sandbox. The sandbox keeps its ID and continues after capture.

The snapshot name must be unique in your project. Use that name (or the snapshot `id`) when you start new sandboxes.

<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"
  sandbox = client.runtime.create()  # defaults to template="base-small"

  sandbox.file.write("/workspace/ready.txt", "installed\n")

  # Disk only (default)
  cold = client.snapshots.create(
      runtime_id=sandbox.runtime_id,
      name="disk-checkpoint",
      kind="cold",
      description="After package install",
  )

  # Disk and memory
  hot = client.snapshots.create(
      runtime_id=sandbox.runtime_id,
      name="memory-checkpoint",
      kind="hot",
  )

  print(cold.id, cold.kind, cold.state)
  print(hot.id, hot.kind, hot.state)
  ```

  ```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"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"

  await sandbox.file.write("/workspace/ready.txt", "installed\n");

  // Disk only (default)
  const cold = await client.snapshots.create(sandbox.runtimeId, 'disk-checkpoint', { kind: 'cold', description: 'After package install' });

  // Disk and memory
  const hot = await client.snapshots.create(sandbox.runtimeId, 'memory-checkpoint', { kind: 'hot' });

  console.log(cold.id, cold.kind, cold.state);
  console.log(hot.id, hot.kind, hot.state);
  ```

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

  gravixlayer snapshot create \
    --name disk-checkpoint \
    --runtime-id "$RT" \
    --kind cold \
    --description "After package install"

  gravixlayer snapshot create \
    --name memory-checkpoint \
    --runtime-id "$RT" \
    --kind hot
  ```

  ```bash cURL theme={"theme":{"light":"catppuccin-latte","dark":"catppuccin-mocha"}}
  # Requires: GRAVIXLAYER_API_KEY
  API="https://api.gravixlayer.ai/v1"

  curl -sS -X POST "$API/agents/snapshots" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"name\": \"disk-checkpoint\",
      \"runtime_id\": \"$RT\",
      \"kind\": \"cold\",
      \"description\": \"After package install\"
    }"

  curl -sS -X POST "$API/agents/snapshots" \
    -H "Authorization: Bearer $GRAVIXLAYER_API_KEY" \
    -H "Content-Type: application/json" \
    -d "{
      \"name\": \"memory-checkpoint\",
      \"runtime_id\": \"$RT\",
      \"kind\": \"hot\"
    }"
  ```
</CodeGroup>

## Parameters

| Parameter     | Type   | Required | Description                                                       |
| ------------- | ------ | -------- | ----------------------------------------------------------------- |
| `runtime_id`  | string | Yes      | Sandbox to capture (`runtime_id`). Must be running or paused      |
| `name`        | string | Yes      | Unique name in the project (max 256 characters; no spaces or `/`) |
| `kind`        | string | No       | `cold` (default) or `hot`                                         |
| `description` | string | No       | Optional note                                                     |

## Response

Returns a [snapshot object](/documentation/agentruntime/snapshots/overview#snapshot-object). `state` is `active` when the snapshot is ready.

## Notes

* You cannot pass both `template` and `snapshot` later when creating a sandbox. Capture first, then [create from the snapshot](/documentation/agentruntime/snapshots/create-from-snapshot).
* Changing files on the source **after** capture does not change the snapshot. New sandboxes see the captured disk, not later edits.
* Open terminals and streams on the source may disconnect for the pause window. Reconnect when the call returns.
* Capture waits until the snapshot is stored. Cold captures of a large disk take longer than hot captures of a light working set.