Skip to main content

msb run

Create a sandbox and run its resolved OCI command. A command after -- replaces the image CMD while preserving its entrypoint; without one, microsandbox runs the image’s default ENTRYPOINT + CMD. Without --name, the sandbox is ephemeral and removed when the command finishes. With --name, it persists for later use.
Common flags: Use msb run --help for the full flag list. Published ports bind to 127.0.0.1 by default. Use an explicit bind address only when the sandbox service should be reachable beyond localhost. On Windows, opening a published port can trigger a Windows Defender Firewall prompt for msb.exe. Keep the bind on 127.0.0.1 for local-only development, and allow private/public network access only when you intentionally bind beyond loopback. On microsandbox cloud, publishing host ports is not available; expose the service through a cloud-reachable endpoint instead.

Network profiles

--net is repeatable and accepts comma-separated profiles. public, private, and host compose; DNS through the sandbox gateway is enabled automatically and only once. all and none are terminal policies and cannot be mixed with the three positive profiles. On microsandbox cloud, the host profile does not refer to the machine running the CLI; use a network endpoint reachable from the cloud worker.
Explicit --net-rule entries are evaluated before profile-generated rules, so they can narrow or deny part of a profile. --net conflicts with --no-net and the --net-default* flags because those select a different policy baseline.

Network rule syntax

--net-rule takes one or more comma-separated rule tokens. The token grammar is:
Targets Wildcard quoting: the rule grammar uses @, :, and , which are shell-significant, so always quote --net-rule values. The *. in suffix shorthand mirrors the syntax already used by --tls-bypass and --secret. Common compositions

msb create

Create and boot a sandbox without running a command. Takes the same flags as msb run (except --detach).
On microsandbox cloud, --replace and --replace-with-timeout are not available; remove the existing sandbox first, then create the replacement.

msb start

Resume a stopped sandbox. Name one or more sandboxes, or select them by label.

msb stop

Graceful shutdown gives the sandbox a chance to finish writing any pending data to disk before it exits, so files written inside the sandbox aren’t lost across a later msb start. If the sandbox is still running after the timeout, it is force-killed. --force and a timeout that elapses both end in a force-kill. Pending writes that the workload hasn’t fsync’d at that point may be lost, with the same durability semantics as a sudden power loss on a physical machine. For durable writes, workloads should fsync important data themselves. On cloud, --force is not yet available; stops are always graceful.

msb restart

Stop and start one or more sandboxes. Running, draining, and paused sandboxes are stopped first, then started from their persisted configuration. Stopped, crashed, and created sandboxes skip the stop phase and are started directly.
msb restart uses the same stop controls as msb stop: --force kills immediately, and --timeout controls how long graceful shutdown gets before force-kill escalation.

msb ping

Check whether one or more running sandbox agents are reachable. msb ping talks to agentd with core.ping and does not refresh the sandbox idle timer.
Use --touch when a successful health check should also refresh the idle timer. Without --touch, ping is a pure reachability check.

msb touch

Explicitly refresh the idle timer for one or more running sandboxes. msb touch sends core.touch; it is the intentional keepalive command for long-lived idle sandboxes.

msb modify

Change a running sandbox’s configuration. Every change is planned and applied all-or-nothing. CPU and memory resize live within the max_cpus / max_memory ceilings; other changes that can’t apply live need --restart or --next-start.
max_cpus and max_memory are boot-time reservations chosen at create time. They default to the effective cpus/memory, which leaves no headroom; live growth beyond them is impossible without a restart. Reserving capacity costs almost nothing (parked vCPUs and lazily-backed memory), so set them above the initial values at create time if the sandbox may need to grow. On microsandbox cloud, these ceilings are not carried; recreate the sandbox to resize beyond its initial values. Live resize is not necessarily instant. When an accepted resize has not fully settled, the apply output includes a convergence table with a STATE column. The values are: applied (requested, actual, and enforced values match), converging (the guest is still onlining CPUs or plugging memory), guest-refused (the guest would not cooperate; the host enforces the new limit anyway), and failed. JSON output (--format json) carries the same states in resize_status. Env and workdir changes on a running sandbox apply to future execs only; running processes keep their current environment. The plan reports this as a warning. --secret NAME@HOST[,HOST...] adds or rotates a secret from the same-named host environment variable, recording a source reference; the value itself never rides in the command. The inline NAME=VALUE@HOST form is rejected, same as on msb create: shell history and process listings would leak the value, so providing a raw value is SDK-only. A live resize may not apply instantly; --format json reports a per-resource resize_status. See Tuning for the change model, or use msb modify --help for the full flag list.

msb exec

Execute a command inside a running sandbox.
The CLI auto-detects whether stdin is a terminal. When interactive, msb exec uses attach mode (TTY, line editing). When piped, it captures output. Use --no-tty to force captured, non-interactive execution even from a terminal.

msb copy

Copy files between the host and a sandbox.
Host-to-sandbox and sandbox-to-host forms follow docker cp syntax. Same-sandbox and cross-sandbox forms are microsandbox extensions. msb copy connects to an existing sandbox and starts it temporarily if needed, following the same lifecycle ownership behavior as msb exec. The shorter msb cp form is available as an alias.

msb logs

Read captured output from a sandbox. Each sandbox stores its captured stdio under <sandbox-dir>/logs/exec.log as JSON Lines, plus runtime/kernel diagnostics in runtime.log/kernel.log. The command works on running and stopped sandboxes alike; there is no protocol traffic, just a file read.
Source tags (the s field in --json output):
  • stdout / stderr: captured from the session’s pipes when running in pipe mode (streams stay separated end to end).
  • output: captured from the session in pty mode. pty allocation merges stdout and stderr at the kernel level inside the guest, so they arrive as a single stream, tagged output rather than mislabelled as stdout.
  • system: synthetic lifecycle markers (--- sandbox started --- / --- sandbox stopped ---) plus diagnostic lines from runtime.log/kernel.log when --source system is requested.
If a sandbox failed to start, msb logs prepends a styled error block reconstructed from boot-error.json. The block tells you the failure stage, errno, and a hint, even though no user-program output was ever captured.

msb ls

List all stored sandboxes.

msb status / ps

Show sandbox status with process details.
The CPUS and MEM columns show the sandbox’s allocation as effective / max, where max is the boot-time hotplug ceiling, the headroom available to a live resize. Values come from the active config for running sandboxes (so an accepted msb modify shows immediately) and from the stored config for stopped ones. For usage rather than allocation, see msb metrics.

msb metrics

Show live CPU, memory, disk, network, and optional upper disk metrics for running sandboxes.
Columns. --watch and the one-shot table render identically:
  • STATE: running (fresh sample from a live runtime), stalled (runtime alive but no sample within 3× its sampling interval; the row shows how long ago the last sample landed), or exited (the preserved terminal sample of a stopped or crashed sandbox).
  • CPU: vCPU-seconds per wall-second over the allocation, e.g. 0.80 / 2c means 0.8 cores busy out of 2 allocated.
  • MEM: guest-used memory over the configured limit.
  • DISK R/W /s, NET RX/TX /s: per-second rates derived from two consecutive samples. The one-shot form samples twice ~500 ms apart to compute them; exited rows show cumulative totals instead.
The CPU and MEM denominators come from the catalog’s active config, so they track live resizes immediately. Sandboxes whose runtime crashed without cleanup are detected by owner-PID liveness and reported as exited, not running. Invocation semantics: --format json and --follow keep the raw cumulative counters (no rate conversion) and add state and cpus fields.

msb inspect

Show detailed configuration and status.

msb rm

Remove one or more sandboxes and their associated state.

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 uninstall

Remove an installed sandbox command.

msb self

Manage the msb installation itself.
msb self update always targets the latest release; it does not accept a version argument. Use msb self downgrade <version> to move to a supported older release. Before a downgrade changes local state, msb runs several safety checks. It verifies the target release and confirms it can read the current local database. It refuses targets below 0.6.0, refuses irreversible state changes, and blocks the operation while matching running sandboxes are active. When a database rollback is needed, msb creates a retained SQLite backup under ~/.microsandbox/db/ unless you pass --no-backup. If rollback metadata marks the image cache affected, msb purges the cache after the database rollback unless you pass --keep-cache. msb always installs the target binary fresh and checks it with msb --version before refreshing command links.