Image commands

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.

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

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

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.

msb load

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

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.

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.

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).

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).

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.

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.

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

Getting Started

SDKs

CLI

msb pull

msb load

msb save

msb images

msb image inspect

msb rmi

msb image prune

msb registry

​msb pull

​msb load

​msb save

​msb images

​msb image inspect

​msb rmi

​msb image prune

​msb registry

msb pull

msb load

msb save

msb images

msb image inspect

msb rmi

msb image prune

msb registry