Snap

A snap is a storage branch point for boxes. It lets you save one file system state and reuse or fork it later.

Commands

⌘Copysys9 run snap import <image-ref>
sys9 run snap fork <snap-id>
sys9 run snap fork --from-box <box-id>
sys9 run snap fork --from-box <box-id> --volume <mount-path>
sys9 run snap ls
sys9 run snap inspect <snap-id>
sys9 run snap tree <snap-id>
sys9 run snap update <snap-id>
sys9 run snap file ls|stat|cat|get <snap-id> ...
sys9 run snap rm <snap-id>

Output

Default output is readable text:

• snap import and snap fork print OK: plus the created snap id.
• snap ls prints a compact table with each snap’s state and size.
• snap inspect prints a summary with a Files link for read-only file access.
• snap tree prints the fork tree around one snap.
• snap rm prints a short confirmation.

Use JSON for automation:

⌘Copysys9 run --json snap inspect <snap-id>
sys9 run --output json snap ls

Import an image

Bring in a new base from an external image:

⌘Copysys9 run snap import public.ecr.aws/docker/library/alpine:3.20

Fork from a snap

Start another branch from an existing saved baseline:

⌘Copysys9 run snap fork <snap-id>

Fork from a box

Fork from a healthy running or stopped box:

⌘Copysys9 run snap fork --from-box my-box

--from-box selects the root file system. The running box pauses briefly, then resumes its existing processes while the snap prepares. The command reports success only when the independent snap is ready to use. No Stop is required. Fork Without Stopping Work walks through it.

To save one Volume instead, select its exact configured mount path:

⌘Copysys9 run snap fork --from-box my-box --volume /state

Root forks exclude Volume data and mount configuration. Each Volume is captured separately; several forks do not form one atomic snapshot across disks. A data-only snap may not be bootable. To put that data into a new box, pass --volume /state,from=<snap-id> to box create; see Back Up and Restore Data.

What a fork captures

Fork synchronizes file system writes already handed to the operating system. Writes racing with capture may appear in either state. Save or flush application-private buffers when their contents must be included. Fork does not guarantee application-level transactions spanning several files.

The parent keeps its processes, memory, open files, and connections. New boxes start fresh from the saved file system; they do not inherit those running processes or connections. Online Fork does not run the parent’s on_start or on_stop hooks.

Concurrent forks from the same source are supported. Each captures its own point in time and returns when its own snap is ready. File transfers and Fork cannot overlap; finish the transfer before retrying. Stop or deletion can cancel a preparing fork, which then returns an error without publishing a partial snap.

List and inspect

⌘Copysys9 run snap ls
sys9 run snap ls --attached true
sys9 run snap inspect <snap-id>
sys9 run snap tree <snap-id>

snap ls shows saved snaps. --attached true shows the disks that boxes are using instead: each box’s root file system and every Volume, with the owning box and mount path.

snap tree shows the whole fork tree that the given snap belongs to: which snap was forked from which. Very old snaps may report that the tree is not available.

Labels

Labels are key=value tags for finding snaps later. They describe the snap, not its files, and a fork does not inherit the labels of its source.

⌘Copysys9 run snap fork <snap-id> --label owner=web --label purpose=base
sys9 run snap ls --label owner=web --label purpose=base
sys9 run snap update <snap-id> --label purpose=archive
sys9 run snap update <snap-id> --clear-labels

snap ls --label returns snaps that match every given label. snap update --label replaces the whole label set.

Remove

⌘Copysys9 run snap rm <snap-id>

Boxes and snaps forked from a snap keep working after it is removed. A snap that is the base of a prewarm profile cannot be removed until that profile is. The disks of a box are removed with the box, not with snap rm.

Share across projects

A snap belongs to one project. Publish it as a Shared Snap to let every project in the org start boxes from it.

Browse files

⌘Copysys9 run snap file ls <snap-id> /work/site
sys9 run snap file stat <snap-id> /work/site/index.html
sys9 run snap file cat <snap-id> /work/site/index.html
sys9 run snap file get <snap-id> /work/site/index.html ./index.html

A detached snap reads its immutable settled filesystem. An attached root Snap uses its owning box’s composed file view; a Volume Snap reads only that Volume. The command stays the same whether the box is running or stopped.