Microsandbox CLI installation and command reference

Interactive sessions are detected automatically; no -it flags are needed. Set an API key to use microsandbox cloud. 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

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

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 branches, groups, and archive operations are local-only. Use msb branch 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`, `branch`, `rm`	Change, branch, or remove sandboxes
`snap`	Save and restore state
`ssh`	SSH sessions, keys, and listeners
`volume`, `volumes`	Manage named storage
`pull`, `load`, `save`, `images`, `rmi`, `image`	Manage cached images
`registry`, `registries`	Manage registry credentials
`context`	Show the active backend
`install`, `uninstall`	Turn sandboxes into shell commands
`doctor`, `update`, `downgrade`, `self`	Manage the CLI installation
`completion`	Generate shell completions

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.

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"

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

Getting Started

SDKs

CLI

CLI overview

Install

Command forms

Quick reference

Quick start

Global options

Shell completion

Command tree

​Install

​Command forms

​Quick reference

​Quick start

​Global options

​Shell completion

​Command tree

Install

Command forms

Quick reference

Quick start

Global options

Shell completion

Command tree