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

# Snapshots

> Save a named checkpoint of a sandbox and start new sandboxes from it

A **snapshot** is a named checkpoint of a sandbox. Capture one from a running sandbox, then start as many new sandboxes as you need from that same point.

The original sandbox keeps running. The snapshot is a separate object you can list, reuse, and delete.

In the API and SDK a sandbox is a **runtime** (`runtime_id`, `client.runtime`, `gravixlayer runtime`). The snippets below use those names.

<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/notes.txt", "warmup done\n")

  snap = client.snapshots.create(
      runtime_id=sandbox.runtime_id,
      name="after-warmup",
      kind="cold",
  )

  child = client.runtime.create(snapshot="after-warmup")
  print(child.file.read("/workspace/notes.txt").content)

  child.kill()
  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"
  const sandbox = await client.runtime.create(); // defaults to template="base-small"
  await sandbox.file.write("/workspace/notes.txt", "warmup done\n");

  const snap = await client.snapshots.create(sandbox.runtimeId, 'after-warmup', { kind: 'cold' });

  const child = await client.runtime.create({ snapshot: 'after-warmup' }); // defaults to template="base-small"
  console.log((await child.file.read("/workspace/notes.txt")).content);

  await child.kill();
  await sandbox.kill();
  ```

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

  RT=$(gravixlayer runtime create --wait --output json | jq -r '.runtime_id')
  gravixlayer runtime files write "$RT" /workspace/notes.txt 'warmup done'

  gravixlayer snapshot create --name after-warmup --runtime-id "$RT" --kind cold

  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
  gravixlayer runtime kill "$RT" -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")

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

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

  curl -sS -X POST "$API/agents/runtime/$RT/files/write" "${AUTH[@]}" \
    -d '{"path":"/workspace/notes.txt","content":"warmup done\n"}'

  curl -sS -X POST "$API/agents/snapshots" "${AUTH[@]}" \
    -d "{\"name\":\"after-warmup\",\"runtime_id\":\"$RT\",\"kind\":\"cold\"}"

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

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

## Cold and hot

Choose the kind when you **create** the snapshot. Restore always starts a **new** sandbox.

| Kind             | What is saved                                             | What the new sandbox does                                                              |
| ---------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `cold` (default) | Disk only — files, packages, and anything written to disk | Boots fresh. Files are there. Running processes are not.                               |
| `hot`            | Disk **and** memory                                       | Continues from the same in-memory state (open processes, REPL variables, loaded data). |

Use **cold** after you have installed packages or written files and you only need the disk. Use **hot** when you also need memory — a loaded model, a running server, or interpreter state.

## Snapshots vs pause vs templates

|                    | [Pause / resume](/documentation/agentruntime/sandbox-management/pause-resume) | Snapshot                                    | [Template](/documentation/agentruntime/templates) |
| ------------------ | ----------------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------- |
| What it is         | Put **this** sandbox to sleep                                                 | A named checkpoint you can reuse            | A starting image                                  |
| Original sandbox   | Stops until you resume it                                                     | Keeps running (pauses only while capturing) | Not involved                                      |
| How many sandboxes | One — the same ID                                                             | Many new sandboxes from one snapshot        | Many new sandboxes from one template              |
| Typical use        | Idle session you will continue                                                | Checkpoint, rollback, parallel copies       | Known clean environment                           |

Start from a [template](/documentation/agentruntime/templates) when every sandbox should look the same. Take a snapshot when the sandbox has already done work you want to keep.

## When to use a snapshot

* Save a sandbox after installs, clones, or data prep, then start later from that point.
* Snapshot **before** a risky step. If it fails, start a new sandbox from the snapshot instead of cleaning up by hand.
* Start several sandboxes from the same checkpoint so they all begin in the same place.

## During capture

The source sandbox pauses briefly, then continues with the **same ID**. Open SSH sessions, terminals, and streams may drop. Reconnect after the snapshot is ready.

<Note>
  Capture can take from under a second (typical hot) to several seconds (cold, larger disk). The create call waits until the snapshot is ready to use.
</Note>

## Region

A snapshot belongs to the **region of the sandbox you captured**. New sandboxes from that snapshot start in the same region. Pass the same `cloud` and `region` you used for the source sandbox. If that region has no capacity, create fails.

## Endpoints

| Method   | Path                                   | Purpose                                                                                       |
| -------- | -------------------------------------- | --------------------------------------------------------------------------------------------- |
| `POST`   | `/v1/agents/snapshots`                 | [Create a snapshot](/documentation/agentruntime/snapshots/create-snapshot)                    |
| `GET`    | `/v1/agents/snapshots`                 | [List snapshots](/documentation/agentruntime/snapshots/list-snapshots)                        |
| `GET`    | `/v1/agents/snapshots/{id_or_name}`    | [Get a snapshot](/documentation/agentruntime/snapshots/get-snapshot)                          |
| `POST`   | `/v1/agents/runtime` with `snapshot`   | [Start a sandbox from a snapshot](/documentation/agentruntime/snapshots/create-from-snapshot) |
| `POST`   | `/v1/agents/snapshots/{id}/activate`   | [Activate](/documentation/agentruntime/snapshots/activate-deactivate)                         |
| `POST`   | `/v1/agents/snapshots/{id}/deactivate` | [Deactivate](/documentation/agentruntime/snapshots/activate-deactivate)                       |
| `DELETE` | `/v1/agents/snapshots/{id_or_name}`    | [Delete](/documentation/agentruntime/snapshots/delete-snapshot)                               |

## Snapshot object

| Field               | Type    | Description                                                  |
| ------------------- | ------- | ------------------------------------------------------------ |
| `id`                | string  | Snapshot UUID                                                |
| `name`              | string  | Name unique in the project. Use this or `id` in later calls  |
| `kind`              | string  | `cold` or `hot`                                              |
| `state`             | string  | `snapshotting`, `active`, `inactive`, `error`, or `removing` |
| `is_active`         | boolean | Whether new sandboxes can be created from it                 |
| `cloud`             | string  | Cloud of the source sandbox                                  |
| `region`            | string  | Region of the source sandbox                                 |
| `vcpu_count`        | integer | Inherited from the source                                    |
| `memory_mb`         | integer | Inherited from the source                                    |
| `disk_size_mb`      | integer | Inherited from the source                                    |
| `size_bytes`        | integer | Stored snapshot size                                         |
| `source_runtime_id` | string  | ID of the sandbox that was captured                          |
| `created_at`        | string  | When the snapshot was created                                |
| `last_used_at`      | string  | When a sandbox was last created from it                      |