Microsandbox CLI installation and command reference

Interactive sessions are detected automatically; no -it flags are needed. Set MSB_BACKEND=cloud and MSB_API_KEY to use microsandbox cloud, or select a saved cloud profile with msb context use <name>. Each reference page marks local-only commands and cloud limitations.

Install

curl -fsSL https://install.microsandbox.dev | sh

brew install superradcompany/tap/microsandbox

irm https://install.microsandbox.dev/windows | iex

On Linux and macOS, the install script writes the runtime to ~/.microsandbox/ and creates command links in ~/.local/bin/. It does not edit shell startup files. If ~/.local/bin is not on your PATH, the installer prints the command to add it. On macOS, Homebrew provides the same CLI through the official tap. On Windows, use PowerShell. Windows support is currently in preview.

Local sandboxes require Linux with glibc 2.28 or newer and KVM, an Apple Silicon Mac, or an x64 or ARM64 machine running Windows 10 or later with Windows Hypervisor Platform enabled. See Linux troubleshooting, macOS troubleshooting, or Windows troubleshooting for setup help.

Check your local setup with:

msb doctor

Quick start

msb create python --name worker
msb exec worker -- python -c "print('hello')"
msb stop worker
msb rm worker

msb run without --name creates an ephemeral sandbox, removed when its command finishes. Named sandboxes persist. Names must contain 1–128 UTF-8 bytes.

Command forms

Use short commands for everyday work. These forms are equivalent:

msb run alpine -- echo hello
msb sandbox run alpine -- echo hello
msb sbx run alpine -- echo hello

Aliases such as ls, rm, cp, and mod also work inside sandbox and sbx. Saved-state operations are grouped under msb snap. The equivalent long form, msb snapshot, is also supported; this documentation uses msb snap consistently:

msb snap create ready --sandbox devbox --full
msb snap restore devbox:ready --name worker
msb snap ls --group devbox
msb snap export devbox:ready --output ready.msb
msb snap import ready.msb --group received

Snapshot behavior, aliases, and backend support

Omit --full to save disk state for a fresh boot. The group defaults to the source sandbox’s name, so the first command creates devbox:ready. Full captures, live forks, groups, and archive operations are local-only. Use msb fork devbox --names worker-a worker-b to create children directly from the same live moment. See Snapshots for backend limits and resource bindings. Existing top-level restore and snapshot save/load commands remain supported.

Quick reference

Commands	Purpose
`run`, `create`, `start`, `stop`, `restart`	Manage sandbox lifecycles
`exec`, `copy`, `logs`	Run commands and access files or output
`ls`, `ps`, `inspect`, `metrics`	Inspect sandboxes
`modify`, `pause`, `resume`, `fork`, `rm`	Change, fork, or remove sandboxes
`snap`	Save and restore state
`ssh`	SSH sessions, keys, and listeners
`volume`, `volumes`	Manage named storage
`df`, `prune`	Inspect local storage and reclaim unused runtime RAM
`pull`, `load`, `save`, `images`, `rmi`, `image`	Manage cached images
`registry`, `registries`	Manage registry credentials
`context`	Inspect the backend, list profiles, or switch your saved preference
`install`, `uninstall`	Turn sandboxes into shell commands
`doctor`, `update`, `downgrade`, `self`	Manage the CLI installation
`completion`	Generate shell completions

Global options

Flag	Description
`--tree`	Display the complete command tree with descriptions
`-L, --levels <N>`	Limit tree depth, counting the selected root as level 0 (requires `--tree`)
`-C, --commands`	Hide flags and arguments in the command tree (requires `--tree`)
`-b, --brief`	Omit descriptions from the command tree (requires `--tree`)
`--error`	Show only errors
`--warn`	Show warnings and errors
`--info`	Show info, warnings, and errors
`--debug`	Show debug output
`--trace`	Show all output including trace

Output formatting

Command results normally go to stdout; progress and diagnostics go to stderr. Use JSON output when a command supports it for scripting.

Streams, units, and output exceptions

Progress, styled action confirmations, warnings, and errors go to stderr. Tables, inspection results, and JSON go to stdout. Empty-list messages retain their command-specific behavior: the registry empty-list message goes to stdout, while listing installed aliases produces no output when none exist. The plain snapshot reindex completion message also remains on stdout.Indented output uses two spaces, with nested content at four spaces. Human-readable image, snapshot, and volume sizes use binary units (KiB, MiB, GiB, TiB); JSON retains its documented numeric fields.

Shell completion

msb completion <shell> prints a completion script for bash, zsh, fish, elvish, or powershell. Write it to the location your shell loads completions from:

# Requires the bash-completion package. Without it, add this line to
# ~/.bashrc instead:  source <(msb completion bash)
mkdir -p ~/.local/share/bash-completion/completions
msb completion bash > ~/.local/share/bash-completion/completions/msb

mkdir -p ~/.zsh/completions
msb completion zsh > ~/.zsh/completions/_msb
# Add this line to ~/.zshrc before compinit runs:
#   fpath=(~/.zsh/completions $fpath)

mkdir -p ~/.config/fish/completions
msb completion fish > ~/.config/fish/completions/msb.fish

mkdir -p ~/.config/elvish/completions
msb completion elvish > ~/.config/elvish/completions/msb.elv
# Add this line to ~/.config/elvish/rc.elv:
#   eval (slurp < ~/.config/elvish/completions/msb.elv)

$completions = Join-Path (Split-Path $PROFILE) "completions"
New-Item -Path $completions -ItemType Directory -Force | Out-Null
msb completion powershell > (Join-Path $completions "msb.ps1")
# Add this line to your profile ($PROFILE):
#   . "$PSScriptRoot/completions/msb.ps1"

Restart your shell. Regenerate saved completions after upgrading.

Command tree

Use --tree as an alternative to --help to see every command, subcommand, and flag at once:

msb --tree

You can scope it to a specific subcommand:

msb image --tree    # Show only image commands
msb volume --tree   # Show only volume commands
msb run --tree      # Show all flags for run
msb sandbox --tree  # Show the canonical sandbox command group
msb sbx run --tree  # Show run flags through the group alias

Limit the depth or hide flags and arguments for a compact command overview:

msb --tree -L 2
msb --tree --commands
msb image --tree --commands -L 1
msb --tree --brief --commands -L 2
msb --tree -Cb -L 2

Tree depth and display rules

-L N (or --levels N) counts the selected root as level 0, so -L 1 shows its immediate children and -L 0 shows only the root. Omitting the limit shows all levels. At the depth limit, an inline marker such as … 4 subcommands, 2 arguments counts the immediate children that were collapsed; arguments include both flags and positional arguments. Hidden commands and options are excluded, and --commands excludes arguments from both the tree and these counts.--brief omits command and argument descriptions and their alignment padding, while retaining names, aliases, value placeholders, and collapse counts. It works with both -L and --commands.

Getting Started

SDKs

CLI

CLI overview

Install

Quick start

Command forms

Quick reference

Global options

Output formatting

Shell completion

Command tree

​Install

​Quick start

​Command forms

​Quick reference

​Global options

​Output formatting

​Shell completion

​Command tree

Install

Quick start

Command forms

Quick reference

Global options

Output formatting

Shell completion

Command tree