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 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.
• snap inspect prints a summary.
• 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.

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.

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 false
sys9 run snap inspect <snap-id>

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.