Workspace Snapshots
A snapshot saves a workspace at one point in time: the container filesystem (installed packages, config changes) and the contents of the bind-mounted volume, including uncommitted code. Devsy stores snapshots as OCI artifacts in a registry you control. Restore a snapshot later or use it to move a workspace to another provider.
Registry required
Devsy pushes snapshots to an OCI registry and pulls them from it. It does not store them locally. You need push and pull access.
Limitations
- The workspace mount must be the only bind mount. Snapshot creation fails if
devcontainer.jsonadds more bind mounts. - Only local providers, such as Docker and Podman, can create snapshots. Machine-provider workspaces cannot.
Create a snapshot
The workspace must exist and be running.
devsy snapshot create my-workspace --registry ghcr.io/my-org/snapshotsThe command prints a snapshot reference. You need it to restore the snapshot. Add --message to describe it.
To skip --registry each time, set a default for the context:
devsy context set -o SNAPSHOT_REGISTRY=ghcr.io/my-org/snapshotsList snapshots
devsy snapshot list my-workspace --registry ghcr.io/my-org/snapshotsThe output lists every snapshot of the workspace, newest first.
Restore a snapshot
devsy snapshot restore <snapshot-ref>Restore creates a workspace from the saved filesystem and volume. It skips the devcontainer build and reuses the original workspace ID. Pass --workspace-id to use another ID or --target-provider to restore onto another provider.
devsy workspace up can also restore a snapshot. Do not combine it with a source argument or --source.
devsy workspace up --from-snapshot <snapshot-ref>Delete a snapshot
devsy snapshot delete <snapshot-ref>snapshot delete removes the manifest from the registry. The registry's garbage collection removes the image and volume blobs.
Export and import
devsy workspace export and devsy workspace import keep the snapshot reference of a restored workspace. The import restores the filesystem and volume only when the manifest still exists and the importing machine can pull from the registry. Otherwise it restores only the workspace metadata.
What the snapshot includes
The committed container image has the label sh.devsy.snapshot=true. Find it with docker images --filter label=sh.devsy.snapshot.
.devsyignore rules apply to the workspace mount, 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.