Devsy
Developing in a Workspace

Workspace Snapshots

A snapshot saves the container filesystem (installed packages and config changes) and the contents of a host bind-mounted workspace, 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 when needed. Creating a snapshot also leaves the committed container image locally after the push, but the registry is still required for the snapshot manifest and volume. You need push and pull access.

Limitations

  • The workspace must use a host bind mount, and it must be the only bind mount. Snapshot creation fails if devcontainer.json adds more bind mounts.
  • Named workspace volumes are not reliably captured. Snapshot creation can fail or capture an unrelated host directory instead. Do not rely on a snapshot to back up a named workspace volume.
  • Other named volumes are not included, even when the workspace bind mount is the only bind mount. Back up and restore their contents separately.
  • 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.

Stop applications that write to the container filesystem or workspace mount before creating the snapshot. Devsy captures them separately while the workspace is running, so changes made during capture can leave the snapshot inconsistent.

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

The 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/snapshots

List snapshots

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

The output lists every snapshot of the workspace, newest first.

Restore a snapshot

devsy snapshot restore <snapshot-ref>

Restore creates a workspace from the saved container filesystem and workspace mount. 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 container filesystem and workspace mount 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.

On this page