# Snapshots (https://luxor.ai/docs/sandbox/snapshots)

> For the complete documentation index, see [llms.txt](https://luxor.ai/llms.txt)

Capture a point-in-time VM snapshot of any Sandbox session, then restore it later as a new session.

A snapshot is a restorable VM capture of one session, including both disk and memory state. Restore a snapshot to spin up a new session in the exact state of the original.

## Manage snapshots

Pick your tool, and the selection syncs across the rest of the page.

### Create

**CLI**
```bash
luxor sandbox snapshot create --session <session-id> --name baseline
```

With expiration:

```bash
luxor sandbox snapshot create \
  --session <session-id> \
  --name before-upgrade \
  --expires-at 2026-03-20T12:00:00Z
```

**TypeScript**
```typescript
const snapshot = await sandbox.createSnapshotAndWait(session.id, {
  name: "after-setup",
});
```

**Go**
One-shot, returns once the snapshot is READY:

```go
snapshot, err := client.CreateSnapshotAndWait(
  ctx,
  session.ID,
  "baseline",
  nil,
  tenkisandbox.DefaultSnapshotCreateTimeout,
)
```

Or kick off the create async and wait separately:

```go
snapshot, err := client.CreateSnapshot(ctx, session.ID, "baseline", nil)
snapshot, err = client.WaitSnapshotReady(ctx, snapshot.ID, 5*time.Minute)
```

**Python**
```python
# From a live sandbox; waits for the snapshot to become READY by default.
snapshot = sb.snapshot(name="after-setup")
```

Or drive it through the client, optionally without waiting:

```python
snapshot = client.snapshots.create_and_wait(sb.id, name="baseline")

# Async, then wait separately:
snapshot = client.snapshots.create(sb.id, name="baseline")
snapshot = client.snapshots.wait_ready(snapshot.id, timeout=300)
```

### List, inspect, delete

**TypeScript**
```typescript
const snapshot = await sandbox.getSnapshot(snapshotId);
const snapshots = await sandbox.listSnapshots();
await sandbox.deleteSnapshot(snapshotId);
```

**Python**
```python
snapshot = client.snapshots.get(snapshot_id)
snapshots = client.snapshots.list()
snapshot = client.snapshots.delete(snapshot_id)
```

**Go**
```go
snapshot, err := client.GetSnapshot(ctx, snapshotID)
snapshots, err := client.ListSnapshots(ctx)
snapshot, err = client.DeleteSnapshot(ctx, snapshotID)
```

**CLI**
```bash
luxor sandbox snapshot list
luxor sandbox snapshot list --json
luxor sandbox snapshot get <snapshot-id>
luxor sandbox snapshot delete <snapshot-id>
```

## Published snapshots stay pinned

Publishing a snapshot creates a version of a registry image. Every registry version keeps its source snapshot pinned, so `snapshot delete` cannot remove that snapshot while any version still references it. Moving a tag does not remove the older version or release its pin.

To release an old snapshot:

1. Make the registry version eligible for deletion. It must not be the image's latest version, must be untagged, and must not be referenced by a share. Publish a newer version, move any tag to another version, and revoke any share that still uses it.

2. Delete the historical registry version by image ref or ID and snapshot ID:

   ```bash
   luxor sandbox registry version delete <image-ref-or-id> --snapshot-id <snapshot-id>
   ```

3. If no other references remain, delete the snapshot if you no longer need it:

   ```bash
   luxor sandbox snapshot delete <snapshot-id>
   ```

Deleting a registry version releases only that version's pin; it does not delete the snapshot itself. Other references can keep the snapshot pinned. In particular, a snapshot created by a template build can remain pinned by that build. A delete against a latest, tagged, or shared version fails, and the error names the rule that still applies.

### Restore

**CLI**
```bash
luxor sandbox snapshot restore <snapshot-id> --name restored-copy
```

`snapshot restore` is a convenience wrapper over:

```bash
luxor sandbox create --snapshot <snapshot-id>
```

**TypeScript**
```typescript
const restored = await sandbox.createAndWait({
  snapshotId: snapshot.id,
});
```

**Go**
```go
restored, err := client.Create(
  ctx,
  tenkisandbox.WithSnapshot(snapshotID),
  tenkisandbox.WithName("restored-copy"),
)
```

**Python**
```python
restored = Sandbox.create(snapshot_id=snapshot.id, name="restored-copy")
```

## Fork a running session

Fork a prepared sandbox to start several independent sessions from the same disk and memory state.
The source briefly pauses for capture, then continues running with its original session ID.
Each child gets a new session ID and its own root disk, so writes in one child do not change the source or another child.

Use the `luxor` CLI **v2.8.0 or later**.
The published TypeScript, Python, and Go SDKs at v1.4.1 do not yet expose `fork`; use the CLI for this workflow.

The source must be `RUNNING` and have no attached volumes.
Forking must be enabled for the workspace.
The workspace must have enough concurrent-session capacity for the source and all requested children.

```bash
luxor sandbox fork <session-id> \
  --count 2 \
  --name-prefix experiment \
  --wait \
  --json
```

* `--count` defaults to 1 and must fit the workspace's maximum children per request, which defaults to 10.
* `--name-prefix experiment` names the children `experiment-1` and `experiment-2`.
* `--wait` waits for the children to finish provisioning.
  Check that each returned session is `RUNNING` before using it.
  Without `--wait`, the children may still be `CREATING` when the command returns.
* `--json` returns `source_id`, `snapshot_id`, and `sessions`.

Each child's metadata also includes `fork_of_session_id` and `fork_snapshot_id`.

Support can disable forking or change the maximum children per request for a workspace.
The workspace's concurrent-session limit still applies separately.
CLI v2.8.0 also caps `--count` at 10; use v2.9.0 or later if the workspace allows more.

A fork creates a snapshot as well as child sessions.
Keep the returned IDs so you can terminate the children and delete the snapshot when finished:

```bash
luxor sandbox terminate --session <child-1-id>
luxor sandbox terminate --session <child-2-id>
luxor sandbox snapshot delete <snapshot-id>
```

Wait for the children to reach `TERMINATED` before deleting their snapshot.
The source keeps running until you pause or terminate it separately.

## Snapshot metadata

A snapshot moves through `CREATING`, `READY`, `FAILED`, `DELETING`, and `DELETED`; wait for `READY` before restoring from it. Each record also reports its size (`size_bytes`, `compressed_bytes`, `memory_bytes`), the session and base image it came from, when it was created, and an optional `expires_at` after which it is deleted.

## Snapshots and secrets

With the `luxor` CLI **2.11.0 or later**, `snapshot get` and `snapshot list` show whether a snapshot was taken from a sandbox with secrets (`has_runtime_secrets`, and a `SECRETS` column in the list).
Restoring one needs workspace edit permission, or an API key with Secrets access, and delivers the current secret versions rather than the old ones.
A secret you deleted since the snapshot is skipped with a `RESTORE_SECRETS_SKIPPED` warning.
See [Secrets and snapshots](https://luxor.ai/docs/sandbox/secrets.md#secrets-and-snapshots).

## Snapshot a terminated sandbox

When Luxor Agent Cloud terminates a sandbox, it keeps the disk for 7 days so you can turn it into a snapshot.
This snapshot restores from disk only, without memory.
Use `luxor sandbox recover <session-id>` with the `luxor` CLI **2.10.0 or later**; see [Recover a terminated sandbox](https://luxor.ai/docs/sandbox/sessions.md#recover-a-terminated-sandbox).

## Volumes are not auto-restored

Snapshots capture disk and memory, but not a session's attached volumes. A restored session is a normal session, so it comes up with no volumes attached. Reattach any volume you need explicitly, at create time or with `volume attach`. See [Volumes](https://luxor.ai/docs/sandbox/volumes.md) for the volume API.

## Errors

Snapshot calls can fail when the snapshot ID is unknown or when creation fails. Every SDK surfaces these as typed errors or exceptions; see the [SDK reference](https://luxor.ai/docs/sandbox/sdk.md#errors) for the names in each language.