# Snapshots (https://tenki.cloud/docs/sandbox/snapshots)

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

Capture a point-in-time VM snapshot of any Tenki 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 [#manage-snapshots]

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

Create [#create]

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

With expiration:

```bash
tenki 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 [#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
tenki sandbox snapshot list
tenki sandbox snapshot list --json
tenki sandbox snapshot get <snapshot-id>
tenki sandbox snapshot delete <snapshot-id>
```

Published snapshots stay pinned [#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
   tenki 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
   tenki 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 [#restore]

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

`snapshot restore` is a convenience wrapper over:

```bash
tenki 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")
```

Snapshot metadata [#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.

Volumes are not auto-restored [#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](/docs/sandbox/volumes) for the volume API.

Errors [#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](/docs/sandbox/sdk#errors) for the names in each language.