> ## Documentation Index
> Fetch the complete documentation index at: https://docs.microsandbox.dev/llms.txt
> Use this file to discover all available pages before exploring further.

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

```bash theme={null}
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 |

<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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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 theme={null}
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, then clean up dangling image artifacts.

```bash theme={null}
msb image prune
msb image prune --yes
msb image prune --format json
```

Prune never removes images used by existing sandboxes. Use `msb rmi --force` when you want to remove a specific image even though it is still referenced.

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

## msb registry

Manage registry authentication.

```bash theme={null}
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