Devsy
Developing in a Workspace

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 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 mount must be the only bind mount. Snapshot creation fails if devcontainer.json adds 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/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 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.

On this page