Microsandbox CLI snapshot commands

Manage saved snapshots with msb snap. See the snapshot guide for workflows. Local selectors accept a group head, group:member, an unambiguous ID or digest, or an artifact path. On cloud, use the snapshot reference returned by the command.

msb snap create

Capture disk state. Add --full to include memory and running processes.

msb snap create ready --sandbox worker

Argument / flag	Description
`NAME`	Positional member name; generated when omitted
`-n`, `--name NAME`	Set the name instead of the positional argument; do not supply both
`--sandbox NAME`	Required source sandbox; `--from-sandbox` remains an alias
`--group GROUP`	Local group; defaults to the source sandbox’s name
`--dest-dir DIR`	Parent directory for local groups
`-o`, `--output PATH`	Capture directly to an archive; conflicts with `--dest-dir` and does not accept `--group`
`--full`	Capture disk, memory, and execution state from a running or paused source
`--guest-flush`	Guest writeback policy: `auto` (default), `required`, or `skip`; see guest flushing
`--integrity`	Record content hashes for later verification
`--label KEY=VALUE`	Attach a label; repeatable
`--plain-tar`	Write uncompressed tar; requires `--output`
`-f`, `--force`	Overwrite an archive output; not allowed for installed members
`-q`, `--quiet`	Suppress output

Local disk capture accepts running, paused, stopped, or crashed sources. Cloud requires a stopped persistent source.

Examples

msb snap create snap --sandbox worker --full
msb snap create ready --sandbox worker --integrity
msb snap create ready --sandbox worker -o ready.msb

Guest flushing is shared by the CLI and SDKs. See guest flushing for policies and examples.

msb snap restore

Restore a saved snapshot into a new sandbox. Disk snapshots boot fresh; full snapshots resume captured execution.

msb snap restore worker:ready --name restored

--name is required. See restore options for memory sharing, disk-only restore, and resource bindings. Existing top-level restore commands remain supported.

msb snap ls

List snapshots. Use --group to filter a local group; it is unavailable on cloud.

msb snap ls
msb snap ls --group worker

Flag	Description
`--group GROUP`	Show only snapshots in this local group
`--format json`	JSON output
`-q`, `--quiet`	Show only digests

msb snap inspect

Show snapshot metadata. Add --verify to check recorded content hashes.

msb snap inspect worker:ready
msb snap inspect worker:ready --verify

msb snap verify

Check recorded content integrity. Local-only; capture with --integrity to record disk hashes.

msb snap verify worker:ready

Without disk hashes, size and structure checks cannot detect same-size corruption. Full snapshots also validate their memory and execution objects. See integrity.

msb snap rm

Delete one or more snapshots.

msb snap rm worker:ready

Flag	Description
`-f`, `--force`	Remove even when indexed children exist
`-q`, `--quiet`	Suppress output

If other group members remain, select another head before removing the current one. --force does not bypass this rule. Removal also refuses an installed copy held by an active restore, export, verification, or import dependency read. --force does not bypass active readers. Independent copies of the same snapshot have independent leases. On Unix, copies sharing a hardlinked descriptor conservatively share reader protection; Windows normally protects each installed directory entry independently. Metadata handles alone do not keep snapshots busy. Saving or removing through a retained SDK handle rejects a replacement artifact at the same path. Deletion atomically retires the artifact directory before removing its contents. A later snapshot listing or removal can recover interrupted cleanup without deleting a new artifact at the original path. Unix readers lock the existing descriptor. Windows readers normally lock an entry-side coordination file outside the removable directory and fall back to the descriptor when an external parent is read-only. Publication and deletion require writable destinations for their coordination records. Concurrent cleanup requires participating SDKs and CLIs; coordinate maintenance when older clients share the storage.

msb snap head

Read a local group’s head, or select a member as its head.

msb snap head worker
msb snap head worker:ready

Use --format json for structured output. The first capture sets the head; later captures advance it only when ancestry proves they descend from it. See snapshot groups.

msb snap export

Export a local snapshot to a compressed .msb archive. The save alias remains supported.

msb snap export worker:ready --output ready.msb --with-image

Flag	Description
`-o`, `--output PATH`	Output archive path; a positional path is also accepted
`--with-image`	Bundle the OCI image for offline restore
`--with-parents`	Include the parent chain
`--plain-tar`	Write uncompressed tar
`--since BASE`	Omit disk layers and RAM objects supplied by an exact base
`--last-layers N`	Export the newest N sealed root-disk layers; the omitted base is needed on import

--since, --last-layers, and --with-parents are mutually exclusive. Export preserves recorded hashes but does not verify them. See incremental exports for base requirements.

msb snap import

Import one or more local archives. The load alias remains supported. Dependencies resolve regardless of input order; all members are validated before publication. Snapshot publication records image ownership before exposing the installed artifact and reports catalog failures. Pending publication and deletion recovery runs during snapshot listing; image pruning also reconciles pending publication.

msb snap import ready.msb

Flag	Description
`--dest DIR`	Parent directory for groups; defaults to the configured snapshot store
`--group GROUP`	Destination group; generated when omitted
`--base SNAPSHOT`	External snapshot or standalone archive for missing dependencies
`--set-head`	Select the imported tip even with divergent ancestry; requires a unique tip

Dependencies come from the batch, matching members in the named group, or --base. Import preserves recorded hashes; run verify to check them.

Examples

msb snap import changes.msb base.msb --group received
msb snap import changes.msb --base worker:ready --group received
msb snap import experiment.msb --group worker --set-head

msb snap reindex

Rebuild the local snapshot index from artifacts on disk. An omitted directory uses the configured snapshot store.

msb snap reindex
msb snap reindex /mnt/snapshots

Command	Purpose
`msb fork`	Copy running execution without saving a snapshot
`msb modify --compact`	Merge sealed disk layers

Getting Started

SDKs

CLI

Snapshot commands

msb snap create

msb snap restore

msb snap ls

msb snap inspect

msb snap verify

msb snap rm

msb snap head

msb snap export

msb snap import

msb snap reindex

​msb snap create

​msb snap restore

​msb snap ls

​msb snap inspect

​msb snap verify

​msb snap rm

​msb snap head

​msb snap export

​msb snap import

​msb snap reindex

​Related commands

msb snap create

msb snap restore

msb snap ls

msb snap inspect

msb snap verify

msb snap rm

msb snap head

msb snap export

msb snap import

msb snap reindex

Related commands