Skip to main content

​
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:3.11 -- python -c "print('hello')"

# Named: persists after exit
msb run --name devbox ubuntu:22.04 -- 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:3.11

# Detached (runs in background)
msb run -d --name worker python:3.11 -- python worker.py
FlagDescription
-n, --nameSandbox name (if omitted, sandbox is ephemeral)
-c, --cpusNumber of virtual CPUs to allocate
-m, --memoryAmount of memory (e.g. 512M, 1G)
-v, --volumeMount a host path or named volume (SOURCE:DEST)
-p, --portForward a host port to the sandbox (HOST:GUEST or HOST:GUEST/udp)
-e, --envSet an environment variable (KEY=VALUE)
-w, --workdirWorking directory inside the sandbox
--shellDefault shell for interactive sessions
-d, --detachRun in background and print the sandbox name
--replaceReplace an existing sandbox with the same name
-q, --quietSuppress progress output
--entrypointOverride the image’s default entrypoint command
-H, --hostnameSet the guest hostname (defaults to sandbox name)
-u, --userRun commands as the specified user (e.g. nobody, 1000, 1000:1000)
--pullWhen to pull the image: always, if-missing (default), never
--log-levelLog verbosity for the sandbox runtime (error, warn, info, debug, trace)
--tmpfsMount a temporary in-memory filesystem (PATH or PATH:SIZE)
--scriptMount a host file as a named script (NAME:PATH)
--max-durationKill the sandbox after this duration (e.g. 30s, 5m, 1h)
--idle-timeoutStop the sandbox after this period of inactivity (e.g. 30s, 5m, 1h)
--no-networkDisable all network access
--dns-block-domainBlock DNS lookups for a domain (returns NXDOMAIN)
--dns-block-suffixBlock DNS lookups for all subdomains of a suffix (e.g. .ads.com)
--no-dns-rebind-protectionAllow DNS responses pointing to private/internal IP addresses
--max-connectionsLimit the number of concurrent network connections
--secretInject a secret that is only sent to an allowed host (ENV=VALUE@HOST)
--on-secret-violationAction when a secret is sent to a disallowed host (block, block-and-log, block-and-terminate)
--tls-interceptIntercept and inspect HTTPS traffic via a built-in TLS proxy
--tls-intercept-portTCP port to apply TLS interception on (default: 443)
--tls-bypassSkip TLS interception for a domain (e.g. *.internal.com)
--no-block-quicAllow QUIC/HTTP3 traffic (blocked by default when TLS interception is on)
--tls-ca-certUse a custom CA certificate for TLS interception (PEM file)
--tls-ca-keyUse a custom CA private key for TLS interception (PEM file)
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:3.11 --name worker -c 2 -m 1G
msb create --replace python:3.11 --name worker   # Replace existing

​
msb start

Resume a stopped sandbox. 
msb start devbox
FlagDescription
-q, --quietSuppress 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
FlagDescription
-f, --forceImmediately kill the sandbox without graceful shutdown
-t, --timeoutSeconds to wait for graceful shutdown before force-killing
-q, --quietSuppress progress output

​
msb exec

Execute a command inside a running sandbox. 
msb exec devbox -- python -c "print('hello')"
msb exec devbox -- ls -la /app
FlagDescription
-t, --ttyAllocate a pseudo-terminal (enables colors, line editing)
-e, --envSet an environment variable (KEY=VALUE)
-w, --workdirOverride working directory
-u, --userRun the command as the specified guest user
--timeoutKill the command after this duration (e.g. 30s, 5m, 1h)
--rlimitSet a POSIX resource limit (e.g. nofile=1024, nproc=64)
-q, --quietSuppress 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 shell

Open an interactive shell session or run a shell script. 
msb shell devbox
msb shell devbox --shell /bin/zsh
msb shell devbox -- echo "hello from shell"
echo "ls -la" | msb shell devbox
FlagDescription
--shellShell program to use (default: sandbox config or /bin/sh)
-u, --userRun the shell as the specified guest user
-q, --quietSuppress progress output

​
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
FlagDescription
--runningShow only running sandboxes
--stoppedShow only stopped sandboxes
--formatOutput format (json)
-q, --quietShow 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
FlagDescription
-a, --allShow all sandboxes, not just running ones
--formatOutput format (json)
-q, --quietShow 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
FlagDescription
--formatOutput format (json)

​
msb inspect

Show detailed configuration and status. 
msb inspect devbox
msb inspect devbox --format json
FlagDescription
--formatOutput 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
FlagDescription
-f, --forceStop the sandbox if running, then remove it
-q, --quietSuppress 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:3.12  # With resource limits
msb install --list                   # List installed commands
FlagDescription
-n, --nameCommand name for the alias (defaults to image name)
-c, --cpusNumber of virtual CPUs to allocate
-m, --memoryAmount of memory (e.g. 512M, 1G)
-v, --volumeMount a host path or named volume (SOURCE:DEST)
-w, --workdirWorking directory inside the sandbox
--shellShell for interactive sessions
-e, --envSet an environment variable (KEY=VALUE)
-f, --forceOverwrite an existing alias with the same name
--no-pullDon’t pull the image before installing
--tmpCreate a fresh sandbox on every invocation (no persistent state)
-l, --listList 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
SubcommandDescription
update (alias: upgrade)Update msb and libkrunfw to the latest release
uninstallRemove msb, libkrunfw, and shell configuration
FlagSubcommandDescription
-f, --forceupdateRe-download even if already on the latest version
-y, --yesuninstallSkip confirmation prompt