Microsandbox CLI setup and management commands

For first-time installation, see the CLI overview.

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

Getting Started

SDKs

CLI

CLI management

msb context

msb install

msb uninstall

msb self

​msb context

​msb install

​msb uninstall

​msb self

msb context

msb install

msb uninstall

msb self