Workspace Snapshots

A snapshot captures a workspace at a point in time: the container's filesystem, such as installed packages and config changes, and the contents of its bind-mounted volume, including uncommitted code. Snapshots are stored as OCI artifacts in a registry you control. You can restore one later or use it to move a workspace to another provider.

LimitationsCopy Anchor Link

• Only workspaces with exactly one bind mount are supported.
• Only local providers, such as Docker and Podman, can create snapshots. Machine-provider workspaces cannot.

Create a snapshotCopy Anchor Link

The workspace must already exist and be running.

devsy snapshot create my-workspace --registry ghcr.io/my-org/snapshots

The command prints the snapshot reference, which you need to restore it. Add --message to describe the snapshot.

To avoid passing --registry each time, set a default for the context:

devsy context set -o SNAPSHOT_REGISTRY=ghcr.io/my-org/snapshots

List snapshotsCopy Anchor Link

devsy snapshot list my-workspace --registry ghcr.io/my-org/snapshots

This shows every snapshot of that workspace, newest first.

Restore a snapshotCopy Anchor Link

devsy snapshot restore <snapshot-ref>

This creates a workspace from the saved filesystem and volume and skips the devcontainer build. It reuses the original workspace ID. Use --workspace-id to pick another one, or --target-provider to restore onto a different provider.

You can also restore as part of devsy workspace up. This cannot be combined with a source argument or --source.

devsy workspace up --from-snapshot <snapshot-ref>

To move a workspace to another provider, restore its snapshot with --target-provider.

Delete a snapshotCopy Anchor Link

devsy snapshot delete <snapshot-ref>

This removes the manifest from the registry. The registry's own garbage collection removes the image and volume blobs.

Export and importCopy Anchor Link

devsy workspace export and devsy workspace import carry the snapshot reference for a workspace that was restored from one. The import restores the real filesystem and volume only if the manifest still exists and the importing machine can pull from the registry. Otherwise only the workspace metadata carries over.

What is includedCopy Anchor Link

The committed container image carries the label sh.devsy.snapshot=true, so you can find it with docker images --filter label=sh.devsy.snapshot.

.devsyignore rules apply to the workspace mount and not to the container image. Files they exclude are missing from the snapshot. If snapshot creation reports missing build-context metadata, run devsy up to refresh it.