---
title: Image commands
sidebarTitle: "Images"
description: Pull and manage OCI images from the CLI
icon: "layer-group"
---

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

1. Explicit SDK auth (`.registry(|r| r.auth(...))`)
2. OS credential store
3. `registries.hosts.<host>.auth` config
4. Docker credential store/config
5. Anonymous