CLI management

Inspect your CLI setup and manage the local installation.

msb context

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

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.

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
`--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. Repeatable
`--net-conf`, `--resource-conf`, `--runtime-conf`, `--fs-conf`, `--secret-conf`, `--script-conf`	Load an explicit scoped config. Repeatable

msb uninstall

Remove an installed sandbox command.

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.

Examples

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

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. 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 for details. See Performance for interpreting these checks, choosing sandbox-level policies, and preparing the host storage and virtualization environment.

Getting Started

SDKs

CLI

msb context

msb install

msb uninstall

msb self

​msb context

​msb install

​msb uninstall

​msb self

msb context

msb install

msb uninstall

msb self