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

# CLI management

> Inspect the active backend, diagnose runtime setup, and manage the microsandbox CLI installation.

For first-time installation, see the [CLI overview](/cli/overview#install).

## msb context

Show the selected backend, API endpoint, and how it was selected. Credentials are not printed. Alias: `msb ctx`.

```bash theme={null}
msb context
msb context --format json
```

## msb install

Install a sandbox as a system command. Creates an executable in `~/.microsandbox/bin/` that launches `msb run` with the specified image and options.

```bash theme={null}
msb install ubuntu                   # Install as 'ubuntu' command
msb install --name nodebox node      # Custom command name
msb install --tmp alpine             # Fresh sandbox every invocation
msb install -c 2 -m 1G python  # With resource limits
msb install --list                   # List installed commands
```

| Flag | Description |
| - | - |
| `-n`, `--name` | Command name for the alias (defaults to image name) |
| `-c`, `--cpus` | Number of virtual CPUs to allocate |
| `-m`, `--memory` | Amount of memory (e.g. `512M`, `1G`) |
| `-v`, `--volume` | Mount a host path or named volume (`SOURCE:DEST[:OPTIONS]`, e.g. `./src:/app:ro,noexec`) |
| `--mount-dir` | Mount a host directory: `SOURCE:DEST[:OPTIONS]`. Supports `quota` and paired `uid`/`gid` |
| `--mount-file` | Mount a host file: `SOURCE:DEST[:OPTIONS]`. Supports `quota` and paired `uid`/`gid` |
| `--mount-disk` | Mount a disk image: `SOURCE:DEST[:OPTIONS]` |
| `--mount-named` | Create or reuse a named volume: `NAME:DEST[:OPTIONS]`. See [kind, size, and quota options](/cli/volume-commands#using-volumes-with-sandboxes) |
| `--security` | In-guest security profile (`default` or `restricted`) |
| `-w`, `--workdir` | Working directory inside the sandbox |
| `--shell` | Shell for interactive sessions |
| `-e`, `--env` | Set an environment variable (`KEY=VALUE`) |
| `-f`, `--force` | Overwrite an existing alias with the same name |
| `--no-pull` | Don't pull the image before installing |
| `--tmp` | Create a fresh sandbox on every invocation (no persistent state) |
| `-l`, `--list` | List all installed sandbox commands |
| `--conf` | Load an explicit sparse [sandbox configuration](/cli/configuration). Repeatable |
| `--net-conf`, `--resource-conf`, `--runtime-conf`, `--fs-conf`, `--secret-conf`, `--script-conf` | Load an explicit [scoped config](/cli/configuration#scoped-config-files). Repeatable |

## msb uninstall

Remove an installed sandbox command.

```bash theme={null}
msb uninstall nodebox
msb uninstall ubuntu alpine   # Remove multiple
```

## msb self

Diagnose, update, downgrade, or remove the CLI. `msb doctor`, `msb update` (alias: `upgrade`), and `msb downgrade` are also available at the top level.

<Accordion title="Examples">
  ```bash theme={null}
  msb doctor                   # Alias for msb self doctor
  msb doctor --fix             # Try supported host setup fixes
  msb self doctor              # Check runtime files and supported host prerequisites
  msb self check               # Alias for doctor
  msb self update               # Update msb and libkrunfw to latest
  msb self update --force       # Re-download even if up to date
  msb self downgrade 0.6.0      # Downgrade to a supported older release
  msb self downgrade 0.6.0 -y   # Skip downgrade confirmations
  msb self uninstall            # Remove msb (with confirmation prompt)
  msb self uninstall --yes      # Skip confirmation
  ```
</Accordion>

| Subcommand | Description |
| - | - |
| `doctor` (alias: `check`) | Check runtime files, supported host virtualization prerequisites, and non-blocking host performance capabilities |
| `update` (alias: `upgrade`) | Update msb and libkrunfw to the latest release and refresh command links |
| `downgrade <version>` | Downgrade msb and compatible local state to a supported older release at or above 0.6.0, refusing unsafe downgrades before touching files or state |
| `uninstall` | Remove msb, libkrunfw, and command links |

`msb self update` always targets the latest release; it does not accept a version argument. Use `msb self downgrade <version>` to move to a supported older release.

Run downgrade from the newer CLI before replacing it: the older binary does not contain rollback steps for newer migrations. If you already installed an older binary and see `database schema is newer than this msb binary`, follow the [catalog recovery steps](/migrations/v0.7#database-schema-is-newer-than-this-msb-binary). [Snapshot groups can also block downgrade](/migrations/v0.7#snapshot-groups-can-block-downgrade).

Only one downgrade can run per installation. A second command fails immediately; wait for the first to finish or cancel it before retrying.

Downgrade checks compatibility and requires affected sandboxes to be stopped. Releases below 0.6.0 and irreversible state changes are rejected. Database rollback creates a retained backup unless `--no-backup` is set; affected image caches are cleared unless `--keep-cache` is set.

| Flag | Subcommand | Description |
| - | - | - |
| `--fix` | `doctor` | Try supported host setup fixes; on Windows this opens an elevated PowerShell prompt to enable Windows Hypervisor Platform without forcing an immediate reboot |
| `-f`, `--force` | `update` | Re-download even if already on the latest version |
| `-f`, `--force` | `downgrade` | Accepted for an explicit reinstall request; downgrade always reinstalls the target and this flag does not bypass safety checks |
| `-y`, `--yes` | `downgrade` | Skip destructive-step confirmations |
| `--keep-cache` | `downgrade` | Keep the image cache even when rollback metadata marks it affected |
| `--no-backup` | `downgrade` | Skip the database backup before rolling back local state |
| `-y`, `--yes` | `uninstall` | Skip confirmation prompt |

Doctor reports supported virtualization and storage capabilities. Disabled interrupt acceleration is a performance warning, not a failed health check; doctor does not reload kernel modules.

A temporary clone probe checks whether flat roots can use native copy-on-write. Probe files are removed afterward. See [Performance](/sandboxes/optimization) for details.

See [Performance](/sandboxes/optimization) for interpreting these checks, choosing sandbox-level policies, and preparing the host storage and virtualization environment.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.