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 cloud compatibility section summarizes 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.

<Note> 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](/troubleshooting/linux), [macOS troubleshooting](/troubleshooting/macos), or [Windows troubleshooting](/troubleshooting/windows) for setup help. </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
msb volumes              # Also: msb vols
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.