Image Commands

Pull and manage OCI images from the CLI

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

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 image ls

List images in the local cache.

msb image ls
msb image ls --format json
msb image ls -q               # References only

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

msb images is a shorthand alias for msb image ls.

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 image rm

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

msb image rm python
msb image rm alpine ubuntu   # Remove multiple

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

msb rmi is a shorthand alias for msb image rm.

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

1. Explicit SDK auth (.registry_auth(...))
2. OS credential store
3. registries.auth config
4. Docker credential store/config
5. Anonymous