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.

Install

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

powershell

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

</CodeGroup>

On Linux and macOS, the installer 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 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

<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

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.