CLI overview

The msb CLI lets you create, manage, and interact with sandboxes from the terminal. It auto-detects TTY and interactivity, so no -it flags are needed. If your terminal is interactive, msb acts accordingly. The same CLI drives microsandbox cloud when an API key is set. A few commands are local-only or limited on cloud, including image-cache commands, msb metrics, bounded msb logs, msb ssh serve, and disk-sized volume creation. Individual pages flag these commands, and the compatibility matrix lists them.

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, and Windows 11 is the tested path.

microsandbox requires glibc-based Linux with KVM enabled, macOS with Apple Silicon (M-series chip), or Windows 11 with Windows Hypervisor Platform enabled. Local sandboxes use hardware virtualization. See Linux troubleshooting, macOS troubleshooting, or Windows troubleshooting for platform-specific notes.

Check your local setup with:

msb doctor

Quick reference

# Run a one-off command (ephemeral, auto-removed)
msb run python -- python -c "print('Hello!')"

# Interactive shell (auto-detects TTY)
msb run alpine -- sh

# Create a persistent sandbox
msb run --name devbox ubuntu -- bash

# Resume later
msb start devbox

# Execute in a running sandbox
msb exec devbox -- sh -c "apt update && apt install -y cowsay && /usr/games/cowsay \"Hello from devbox\""

# Manage
msb ls                   # List all sandboxes
msb ps                   # Running sandboxes only
msb metrics              # Live CPU/memory/network stats
msb inspect devbox       # Detailed info
msb logs devbox          # Captured stdout/stderr (works on stopped sandboxes too)
msb logs devbox -f       # Follow live
msb stop devbox          # Graceful shutdown
msb rm devbox            # Remove stopped sandbox

# SSH
msb ssh authorize --file ~/.ssh/id_ed25519.pub
msb ssh devbox
msb ssh devbox -- uname -a
msb ssh serve devbox --host 127.0.0.1 --port 2222

# Images
msb pull python       # Pre-pull to cache
msb images            # List cached images
msb rmi python        # Remove a cached image

# Volumes
msb volume create data --size 10G
msb volume ls
msb volume rm data

# Install as a system command
msb install ubuntu       # Install as 'ubuntu' command
msb uninstall ubuntu     # Remove installed command

# Self-management
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 update          # Update msb to latest
msb self downgrade 0.6.0 # Downgrade to a supported older release
msb self uninstall       # Remove msb

# Shell completion
msb completion zsh       # Print the zsh completion script

Unnamed sandboxes (no --name flag) are ephemeral. They’re automatically removed when the command finishes. Named sandboxes persist and can be stopped, restarted, and inspected later. Names must be non-empty and no longer than 128 UTF-8 bytes.

Global options

Flag	Description
`--tree`	Display the complete command tree with descriptions
`--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

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"

Then restart your shell.

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

For detailed command reference, see Sandbox commands, SSH commands, Volume commands, and Image commands. For the SSH model and usage patterns, see SSH.

Getting Started

SDKs

CLI

Install

Quick reference

Global options

Shell completion

Command tree

​Install

​Quick reference

​Global options

​Shell completion

​Command tree

Install

Quick reference

Global options

Shell completion

Command tree