CLI overview - Microsandbox

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

<CodeGroup> ```bash CLI (Linux & macOS) curl -fsSL https://install.microsandbox.dev | sh ```

bash

brew install superradcompany/tap/microsandbox

powershell

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

</CodeGroup>

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.

<Note> 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](/troubleshooting/linux), [macOS troubleshooting](/troubleshooting/macos), or [Windows troubleshooting](/troubleshooting/windows) for platform-specific notes. </Note>

Check your local setup with:

bash

msb doctor

Quick reference

bash

# 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

<Tip> 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. </Tip>

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:

<CodeGroup> ```bash bash # 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 ```

zsh

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

fish

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

elvish

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)

powershell

$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"

</CodeGroup>

Then restart your shell.

Command tree

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

bash

msb --tree

You can scope it to a specific subcommand:

bash

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.