Image commands - Microsandbox

<Tooltip tip="Image commands manage the local cache. On microsandbox cloud, specify an OCI image when creating the sandbox and it is pulled for you."><span className="msb-badge-local">Local-only <Icon icon="circle-info" size={11} /></span></Tooltip>

msb pull

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.

bash

msb pull python
msb pull alpine
msb pull ghcr.io/my-org/my-image:v1
msb pull python --materialize flat
msb pull python --materialize all

Expanded form: msb image pull.

Flag	Description
`-f`, `--force`	Force re-download even if cached
`-q`, `--quiet`	Suppress progress output
`--insecure`	Connect over plain HTTP instead of HTTPS
`--ca-certs <PATH>`	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.

<Tip> 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. </Tip>

msb load

Load a Docker image archive or OCI Image Layout archive into the local microsandbox cache.

bash

docker save my-image:latest | msb load
msb load --input my-image.tar
msb load --input oci-layout.tar --tag my-image:latest

Expanded form: msb image load.

Flag	Description
`-i`, `--input <PATH>`	Read archive from a tar file instead of stdin
`-t`, `--tag <REF>`	Add a local image reference to the first imported image
`-q`, `--quiet`	Suppress output

msb save

Save one or more cached images as a Docker-compatible archive or OCI Image Layout archive.

bash

msb save --output my-image.tar my-image:latest
msb save --format oci --output my-image.oci.tar my-image:latest
msb 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.

msb images

List images in the local cache.

bash

msb images
msb images --format json
msb images -q               # References only

Expanded form: msb image ls.

Flag	Description
`--format`	Output format (`json`)
`-q`, `--quiet`	Show only image references

msb image inspect

Show detailed metadata for a cached image (manifest, layers, config).

bash

msb image inspect python
msb image inspect python --format json

Flag	Description
`--format`	Output format (`json`)

msb rmi

Remove one or more cached images and their layers (layers shared with other images are kept).

bash

msb rmi python
msb rmi alpine ubuntu   # Remove multiple

Expanded form: msb image rm.

Flag	Description
`-f`, `--force`	Remove even if the image is used by existing sandboxes
`-q`, `--quiet`	Suppress output

msb image prune

Remove cached images that are not used by any sandbox or indexed snapshot, then clean up dangling image artifacts.

bash

msb image prune
msb image prune --yes
msb image prune --format json

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.

Flag	Description
`-y`, `--yes`	Skip the confirmation prompt
`--format`	Output format (`json`)
`-q`, `--quiet`	Suppress output

msb registry

Manage registry authentication.

bash

msb registry login ghcr.io --username octocat
printf '%s\n' "$GHCR_TOKEN" | msb registry login ghcr.io --username octocat --password-stdin
msb registry logout ghcr.io
msb registry ls

Subcommand	Description
`login`	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