Pre-pull an image to the local cache. Layers are fetched in parallel with per-layer progress bars. Once cached, layers are content-addressable and deduplicated, so shared layers across images are only stored once.
Path to a PEM file with additional CA root certificates
--materialize <MODE>
Explicitly prepare layered, flat, or all rootfs artifacts
flat creates a reusable, validated raw ext4 base with no guest OverlayFS in the final rootfs. Shared layers are downloaded and verified once, cached as EROFS by their uncompressed OCI diff_id, and reused across image manifests. Flat mode merges those EROFS inputs into ext4 without producing layered-only fsmeta or VMDK artifacts. all runs the shared layer stage once and prepares both representations.When --materialize is omitted, msb pull follows sandbox_defaults.oci.root_disk: a flat default prepares the flat artifact, while the built-in managed default prepares the layered representation. An explicit flag always wins.Flat artifacts live under the configured cache directory. flat/refs/<manifest>.json records the requested manifest and verified result, flat/blobs/<artifact>.raw stores immutable content-addressed ext4 bytes, and flat/locks/<derivation>.lock coordinates concurrent materialization. A ref whose blob is missing or has the wrong logical size is treated as a cache miss.
Pre-pulling is useful when you want sandbox creation to be instant. Without a pre-pull, the first Sandbox.create with a new image will block on the download.
Save one or more cached images as a Docker-compatible archive or OCI Image Layout archive.
msb save --output my-image.tar my-image:latestmsb save --format oci --output my-image.oci.tar my-image:latestmsb save my-image:latest > my-image.tar
Expanded form: msb image save.
Flag
Description
--format <FORMAT>
Archive format (docker, oci; default: docker)
-o, --output <PATH>
Write archive to a tar file instead of stdout
-q, --quiet
Suppress output
msb save re-exports images from microsandbox’s EROFS cache. The saved archive is semantically equivalent, but it is not a byte-for-byte copy of the originally pulled image. Manifest digest and layer digests can change because layer tar streams are regenerated.
Prune never removes images used by existing sandboxes or indexed snapshots. It also cleans up image metadata, unreachable manifests, orphaned layers, layer EROFS artifacts, fsmeta EROFS artifacts, and VMDK descriptor artifacts. Use msb rmi --force when you want to remove a specific image even though it is still referenced by a sandbox.
Store credentials for a registry in the OS credential store
logout
Remove stored credentials for a registry
list (alias: ls)
List configured registries without printing secrets
msb registry login flags:
Flag
Description
--username
Registry username
--password-stdin
Read password from stdin
msb registry login stores the secret in the OS credential store (for example Keychain, Credential Manager, or Secret Service) and writes only metadata to ~/.microsandbox/config.json.For CI or other headless environments, configure registries.hosts.<host>.auth in ~/.microsandbox/config.json with password_env. Advanced host setups can also use secret_name to point at a file-backed secret under ~/.microsandbox/secrets/registries/.When pulling from a registry, microsandbox resolves auth in this order:
Explicit SDK auth (.registry(|r| r.auth(...)))
OS credential store
registries.hosts.<host>.auth config
Docker credential store/config
Anonymous
⌘I
Assistant
Responses are generated using AI and may contain mistakes.
