Snapshots
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
const snapshot = await sandbox.createSnapshotAndWait(session.id, {
name: "after-setup",
});List, inspect, delete
const snapshot = await sandbox.getSnapshot(snapshotId);
const snapshots = await sandbox.listSnapshots();
await sandbox.deleteSnapshot(snapshotId);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:
-
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.
-
Delete the historical registry version by image ref or ID and snapshot ID:
Terminalluxor sandbox registry version delete <image-ref-or-id> --snapshot-id <snapshot-id> -
If no other references remain, delete the snapshot if you no longer need it:
Terminalluxor 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
const restored = await sandbox.createAndWait({
snapshotId: snapshot.id,
});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.
luxor sandbox fork <session-id> \
--count 2 \
--name-prefix experiment \
--wait \
--json--countdefaults to 1 and must fit the workspace's maximum children per request, which defaults to 10.--name-prefix experimentnames the childrenexperiment-1andexperiment-2.--waitwaits for the children to finish provisioning. Check that each returned session isRUNNINGbefore using it. Without--wait, the children may still beCREATINGwhen the command returns.--jsonreturnssource_id,snapshot_id, andsessions.
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:
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.
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.
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 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 for the names in each language.