Workspace Snapshots

Snapshots allow a workspace to start quickly in a customized state by skipping lengthy setup scripts. Three types of snapshots contribute to workspace customization:

Base snapshot: provides the root filesystem.
Home snapshot: restores files inside the owner's home directory.
Personal snapshot: restores personalized files inside the home directory specific to the owner.

For a conceptual overview, see Snapshot.

Base Snapshot

The base snapshot provides the root filesystem for a workspace, excluding the following directories (which contain runtime or sensitive data):

/home — may contain sensitive information or large files not worth sharing
/var/log/sandbox — runtime logs tied to the workspace's lifetime
/var/lib/sandbox — runtime state files tied to the workspace's lifetime
/var/lib/docker — may contain large container image layers
/var/lib/buildkit — similar to docker, may contain large image layers
/tmp — temporary files

Base snapshots are stored as standard OCI container images. Any OCI container image from an authorized container registry can be used directly as a base snapshot, provided it contains a standard Linux root filesystem using GNU libc (Debian-based). Alpine images using musl libc are not currently supported.

A base snapshot is shared across the org and can be used by any sandbox.

Creating a Base Snapshot

Create a base snapshot from the current root filesystem of a running workspace:

cs snapshot create base-example

Replace base-example with the desired snapshot name. Snapshot names are shared in a single namespace across all snapshot types — the name must be unique regardless of type.

If the command is not being run inside the target workspace, add the -W SANDBOX/WORKSPACE flag to specify the target.

Using a Base Snapshot

Reference a base snapshot in a workspace definition:

workspaces:
- name: example
  base_snapshot: NAME

To use a custom OCI container image directly, prefix the image reference with oci://:

workspaces:
- name: example
  base_snapshot: oci://registry-host/path/image:tag

Regardless of the base snapshot kind, a new base snapshot can always be created from the workspace using cs snapshot create. The new snapshot will contain all layers from the current base snapshot plus a new layer of changed files.

Home Snapshot

A home snapshot is a single-layer OCI container image that captures explicitly listed files under $HOME (typically /home/owner) and restores them when a new workspace is created.

Home snapshots are shared across the org and can be used by any sandbox.

Creating a Home Snapshot

Unlike base snapshots, a home snapshot requires an explicit list of files to include. Create the file $HOME/.snapshot/includes.txt to specify which folders and files to capture:

.bashrc
.bash_logout
.profile
.config
.local
.cache
.vscode-server/extensions
.vscode-remote/extensions
.vscode-remote/data/User/extensions.json

Optionally, create $HOME/.snapshot/excludes.txt in the same format to exclude specific items (exclusions are applied after inclusions).

Once the include list is ready, create the snapshot:

cs snapshot create --home NAME

The NAME must be unique across all snapshots regardless of type.

Using a Home Snapshot

Reference a home snapshot in a workspace definition:

workspaces:
- name: example
  home_snapshot: NAME

If unspecified, nothing is restored in the home directory.

Personal Snapshot

A personal snapshot is similar to a home snapshot but belongs only to the owner. It is only visible and applicable to sandboxes belonging to the same user. Personal snapshots are used for applying individual customizations to workspaces — such as personal shell configurations, scripts, and dotfiles — that should not be shared with other team members.

A user may create multiple personal snapshots and designate one as the default. The default personal snapshot is automatically applied to all workspaces in every new sandbox the user creates. Without a default personal snapshot, nothing is applied.

Creating a Personal Snapshot

Creating a personal snapshot requires an explicit include list, in the file ~/.snapshot.personal/includes.txt (note: .snapshot.personal, not .snapshot). Optionally, ~/.snapshot.personal/excludes.txt can be used to exclude specific files.

Once the file list is prepared:

cs snapshot create --personal NAME --set-personal-default

Where NAME is the snapshot name, unique within the current user's personal snapshot namespace (personal snapshot names do not conflict with base/home snapshots or other users' personal snapshots).

The --set-personal-default flag sets the newly created snapshot as the default. Remove this flag if you do not want to change the current default.

Using a Personal Snapshot

When set as default, a personal snapshot is applied automatically to any workspace in a newly created sandbox belonging to the owner. No explicit action is required.

Snapshot Application Order

When a workspace is created, snapshots are applied in this order:

Base snapshot
Home snapshot (if specified)
Personal snapshot (if a default is set)

Files in later snapshots overwrite those with the same path from earlier snapshots. This means personal snapshot files take precedence over home snapshot files.