Snapshot

A Snapshot in the Crafting Sandbox system is an object that captures persistent state as files in the filesystem of a workload at a point in time. Snapshots can be referenced in a Template definition so that when a sandbox is created, the captured state is automatically restored, allowing developers to skip lengthy setup procedures.

Types

The Crafting Sandbox system supports the following types of snapshots:

Base Snapshot

A base snapshot captures the root filesystem of a workspace, excluding these directories:

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

Base snapshots are stored in standard OCI container image format. Any OCI container image from an authorized container registry can also be used directly as a base snapshot to restore the root filesystem of a workspace. A base snapshot is shared across the org and can be referenced and used by any sandbox.

Home Snapshot

A home snapshot captures files under $HOME (typically /home/owner) that are explicitly listed by the user. Because the home directory contains personalized and sensitive files — and potentially large files not worth sharing — an explicit list is required. Home snapshots are shared across the org and can be used by any sandbox.

Personal Snapshot

A personal snapshot is a special kind of home snapshot that belongs only to the sandbox owner. It is only visible and applicable to sandboxes owned by the same user. Personal snapshots are used for applying personalized customizations to workspaces, such as shell configurations, personal scripts, and dotfiles.

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

Dependency Snapshot

A dependency snapshot captures the persistent data files of a dependency service (e.g. a MySQL or PostgreSQL database). Dependency snapshots are used to quickly restore a service to a known state when a sandbox is created, or to revert data during development. They are shared across the org.

See Dependency Snapshot for full details.

Container Snapshot

A container snapshot captures all persistent volumes attached to a container workload. It is a collection of volume data and can only be restored to container workloads with exactly the same names and order of attached volumes. Container snapshots are shared across the org.

See Container Snapshot for full details.

Snapshot Application Order

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

Base snapshot — restores the root filesystem
Home snapshot — restores selected files in the home directory (if specified)
Personal snapshot — applies personalized files over the home snapshot (if a default is set)

Files in a later snapshot overwrite files with the same path from earlier snapshots.

All snapshot types are shared across the org and can be referenced in templates or sandbox definitions, except personal snapshots, which are private to the owning user.