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

bash

curl -fsSL https://install.microsandbox.dev | sh

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.

<Note> Windows support is currently in preview. A Windows MSI or winget package is not published yet; use the PowerShell installer from the latest GitHub release:

powershell

irm https://github.com/superradcompany/microsandbox/releases/latest/download/install.ps1 | iex

</Note> <Note> microsandbox requires Linux with KVM enabled, macOS with Apple Silicon (M-series chip), or Windows with Windows Hypervisor Platform enabled. Local sandboxes use hardware virtualization. </Note>

On Windows, run the doctor check before starting local sandboxes:

powershell

msb doctor

If it reports that Windows Hypervisor Platform is unavailable, let msb open the elevated fix prompt:

powershell

msb doctor --fix

You can also enable the optional feature manually from an elevated PowerShell:

powershell

Enable-WindowsOptionalFeature -Online -FeatureName HypervisorPlatform -All -NoRestart

Reboot after the command completes. HypervisorPlatform is the WHP API surface used by libkrun and is separate from VirtualMachinePlatform, which WSL2 and Docker Desktop often enable. See Windows troubleshooting for failure-specific checks.

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 and host virtualization prerequisites
msb self update          # Update msb to latest
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.