Sandbox Commands

Create, run, and interact with sandboxes from the CLI

msb run

Create a sandbox and optionally run a command. Without --name, the sandbox is ephemeral and removed when the command finishes. With --name, it persists for later use.

# Ephemeral: runs and cleans up
msb run python -- python -c "print('hello')"

# Named: persists after exit
msb run --name devbox ubuntu -- bash

# With volumes, ports, and environment
msb run --name api \
  -v ./src:/app \
  -v pydata:/data \
  -p 8000:8000 \
  -e DEBUG=true \
  -w /app \
  python

# Detached (runs in background)
msb run -d --name worker python -- python worker.py

Flag	Description
-n, --name	Sandbox name (if omitted, sandbox is ephemeral)
-c, --cpus	Number of virtual CPUs to allocate
-m, --memory	Amount of memory (e.g. 512M, 1G)
-v, --volume	Mount a host path or named volume (SOURCE:DEST)
-p, --port	Forward a host port to the sandbox (HOST:GUEST or HOST:GUEST/udp)
-e, --env	Set an environment variable (KEY=VALUE)
-w, --workdir	Working directory inside the sandbox
--shell	Default shell for interactive sessions
-t, --tty	Allocate a pseudo-terminal (enables colors, line editing)
-d, --detach	Run in background and print the sandbox name
--timeout	Kill the command after this duration (e.g. 30s, 5m, 1h). Per-command; the sandbox stays alive
--rlimit	Set a POSIX resource limit (e.g. nofile=1024, nproc=64, as=1073741824)
--detach-keys	Key sequence to detach from interactive session (default: ctrl-])
--replace	Replace an existing sandbox with the same name
-q, --quiet	Suppress progress output
--entrypoint	Override the image’s default entrypoint command
-H, --hostname	Set the guest hostname (defaults to sandbox name)
-u, --user	Run commands as the specified user (e.g. nobody, 1000, 1000:1000)
--pull	When to pull the image: always, if-missing (default), never
--log-level	Log verbosity for the sandbox runtime (error, warn, info, debug, trace)
--tmpfs	Mount a temporary in-memory filesystem (PATH or PATH:SIZE)
--script	Register an inline script (NAME=BODY). Available at /.msb/scripts/<name> and on PATH
--script-path	Register a script from a host file (NAME:PATH). Same destination as --script
--max-duration	Kill the entire sandbox after this duration (e.g. 30s, 5m, 1h). Sandbox-level lifetime limit
--idle-timeout	Stop the sandbox after this period of inactivity (e.g. 30s, 5m, 1h)
--no-network	Disable all network access
--network-policy	Control which destinations are reachable from the sandbox. Accepted values: none (no network), public-only (default — public internet only), nonlocal (public + private/LAN; blocks loopback, link-local, and metadata), allow-all (unrestricted)
--deny-domain	Deny egress to a domain. Repeatable. Adds a deny Domain("...") policy rule that fires at DNS resolution (REFUSED), TLS first-flight (SNI), and TCP egress (cache fallback)
--deny-domain-suffix	Deny egress to all subdomains of a suffix (e.g. .ads.com). Repeatable. Adds a deny DomainSuffix("...") policy rule
--no-dns-rebind-protection	Allow DNS responses pointing to private/internal IP addresses
--dns-nameserver	Nameserver to forward DNS queries to (repeatable; IP or IP:PORT). Overrides the host’s /etc/resolv.conf
--dns-query-timeout-ms	Per-DNS-query timeout in milliseconds (default: 5000)
--max-connections	Limit the number of concurrent network connections
--trust-host-cas	Ship the host’s trusted root CAs into the guest so outbound TLS works behind corporate MITM proxies (Cloudflare Warp Zero Trust, Zscaler, etc.) whose gateway CA is installed on the host but unknown to the guest’s stock bundle. Opt-in; by default the guest validates against its stock Mozilla bundle only
--secret	Inject a secret that is only sent to an allowed host (ENV=VALUE@HOST)
--on-secret-violation	Action when a secret is sent to a disallowed host (block, block-and-log, block-and-terminate)
--tls-intercept	Intercept and inspect HTTPS traffic via a built-in TLS proxy
--tls-intercept-port	TCP port to apply TLS interception on (default: 443)
--tls-bypass	Skip TLS interception for a domain (e.g. *.internal.com)
--no-block-quic	Allow QUIC/HTTP3 traffic (blocked by default when TLS interception is on)
--tls-intercept-ca-cert	Use a custom CA certificate for TLS interception (PEM file)
--tls-intercept-ca-key	Use a custom CA private key for TLS interception (PEM file)
--tls-upstream-ca-cert	Trust an additional CA certificate for upstream server verification (PEM file). Can be specified multiple times

When no -- command is given, the image’s entrypoint and cmd are used as the default process. If the image has neither, an interactive shell is started. When a command is given via --, it replaces the image cmd but the entrypoint is preserved. See Image config inheritance for details.

msb create

Create and boot a sandbox without running a command. Takes the same flags as msb run (except --detach).

msb create python --name worker -c 2 -m 1G
msb create --replace python --name worker   # Replace existing

msb start

Resume a stopped sandbox.

msb start devbox

Flag	Description
-q, --quiet	Suppress progress output

msb stop

msb stop devbox                # Graceful shutdown
msb stop --force devbox        # Force kill immediately
msb stop -t 10 devbox          # Wait 10s then force kill

Flag	Description
-f, --force	Immediately kill the sandbox without graceful shutdown
-t, --timeout	Seconds to wait for graceful shutdown before force-killing
-q, --quiet	Suppress progress output

msb exec

Execute a command inside a running sandbox.

msb exec devbox -- python -c "print('hello')"
msb exec devbox -- ls -la /app

Flag	Description
-t, --tty	Allocate a pseudo-terminal (enables colors, line editing)
-e, --env	Set an environment variable (KEY=VALUE)
-w, --workdir	Override working directory
-u, --user	Run the command as the specified guest user
--timeout	Kill the command after this duration (e.g. 30s, 5m, 1h)
--rlimit	Set a POSIX resource limit (e.g. nofile=1024, nproc=64)
-q, --quiet	Suppress progress output

The CLI auto-detects whether stdin is a terminal. When interactive, msb exec uses attach mode (TTY, line editing). When piped, it captures output. No -i flag is needed.

msb ls

List all stored sandboxes.

msb ls                    # All sandboxes (running and stopped)
msb ls --running          # Running sandboxes only
msb ls --stopped          # Stopped sandboxes only
msb ls --format json      # JSON output
msb ls -q                 # Names only

Flag	Description
--running	Show only running sandboxes
--stopped	Show only stopped sandboxes
--format	Output format (json)
-q, --quiet	Show only sandbox names

msb status / ps

Show sandbox status with process details.

msb ps                    # Running sandboxes
msb ps my-app             # Single sandbox
msb ps -a                 # All sandboxes (including stopped)
msb ps --format json      # JSON output

Flag	Description
-a, --all	Show all sandboxes, not just running ones
--format	Output format (json)
-q, --quiet	Show only sandbox names

msb metrics

Show live CPU, memory, disk, and network metrics for running sandboxes.

msb metrics               # All running sandboxes
msb metrics my-app        # Single sandbox
msb metrics --format json # JSON output

Flag	Description
--format	Output format (json)

msb inspect

Show detailed configuration and status.

msb inspect devbox
msb inspect devbox --format json

Flag	Description
--format	Output format (json)

msb rm

Remove one or more sandboxes and their associated state.

msb rm devbox
msb rm --force devbox     # Stop and remove in one step
msb rm worker-1 worker-2  # Remove multiple

Flag	Description
-f, --force	Stop the sandbox if running, then remove it
-q, --quiet	Suppress progress output

msb install

Install a sandbox as a system command. Creates an executable in ~/.microsandbox/bin/ that launches msb run with the specified image and options.

msb install ubuntu                   # Install as 'ubuntu' command
msb install --name nodebox node      # Custom command name
msb install --tmp alpine             # Fresh sandbox every invocation
msb install -c 2 -m 1G python  # With resource limits
msb install --list                   # List installed commands

Flag	Description
-n, --name	Command name for the alias (defaults to image name)
-c, --cpus	Number of virtual CPUs to allocate
-m, --memory	Amount of memory (e.g. 512M, 1G)
-v, --volume	Mount a host path or named volume (SOURCE:DEST)
-w, --workdir	Working directory inside the sandbox
--shell	Shell for interactive sessions
-e, --env	Set an environment variable (KEY=VALUE)
-f, --force	Overwrite an existing alias with the same name
--no-pull	Don’t pull the image before installing
--tmp	Create a fresh sandbox on every invocation (no persistent state)
-l, --list	List all installed sandbox commands

msb uninstall

Remove an installed sandbox command.

msb uninstall nodebox
msb uninstall ubuntu alpine   # Remove multiple

msb self

Manage the msb installation itself.

msb self update               # Update msb and libkrunfw to latest
msb self update --force       # Re-download even if up to date
msb self uninstall            # Remove msb (with confirmation prompt)
msb self uninstall --yes      # Skip confirmation

Subcommand	Description
update (alias: upgrade)	Update msb and libkrunfw to the latest release
uninstall	Remove msb, libkrunfw, and shell configuration

Flag	Subcommand	Description
-f, --force	update	Re-download even if already on the latest version
-y, --yes	uninstall	Skip confirmation prompt