A snapshot captures the workspace’s root filesystem. Use it before changing system packages or other files on that disk. It does not capture attached persistent volumes, memory, or running processes.
The current implementation retains one snapshot per workspace. Creating a new snapshot replaces the previous checkpoint. Back up application data separately.
How Snapshots Work
Stop the workspace, then snapshot its root disk. Restore is limited to the same workspace. Sparse copying avoids copying unallocated space, but the actual result size depends on filesystem usage; do not size backups using a fixed percentage.
Create a Snapshot
Run on your local machine after authenticating. Choose the intended workspace before stopping it:
Record the snapshot ID returned by the platform. Listing it verifies the checkpoint exists; a healthy running app verifies the workspace restarted successfully.
List Snapshots
For a Specific Workspace
All Your Snapshots
Use the command’s actual output envelope and size fields rather than assuming a bare JSON array or fixed unit. See snapshot commands.
Restore a Snapshot
Follow restore a workspace snapshot. Restoring overwrites the root disk but does not rewind volume-backed databases.
Delete a Snapshot
Deletion permanently removes that checkpoint. Confirm the ID before running the command.
Storage and Sizing
Use the reported size from the snapshot list/API. Root-disk size and persistent-volume capacity are different measurements. See recovery boundaries.
Use Cases
Pre-Demo Checkpoint
Capture a stopped workspace before changing its system environment. Test that the app and its current data remain compatible after restoration.
Experiment Branching
Use a checkpoint to undo root-filesystem changes in the same workspace. This endpoint is not a cross-workspace cloning workflow.
Disaster Recovery
Keep application-consistent data backups outside the workspace. A single replaceable root-disk checkpoint is not a multi-version backup archive.
Reproducibility
Use workspace images to reproduce an installed runtime, and a snapshot to checkpoint this workspace’s root disk.
Complete Workflow Example
The create/list/start commands above checkpoint the root disk. For the restoration sequence and verification steps, follow restore a snapshot.
Limitations
- Stop the workspace before snapshot or restore.
- Only the root filesystem is included, not attached volumes or memory.
- Restore is scoped to the original workspace.
- A new snapshot replaces the prior checkpoint.
Next Steps
