docs/cli/image-commands.mdx
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 |
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 |
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.
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 |
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) |
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 |
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.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:
.registry_auth(...))registries.auth config