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.
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.
--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 asmsb run (except --detach).
--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
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.
--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 themax_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.msb copy
Copy files between the host and a sandbox.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, taggedoutputrather than mislabelled asstdout.system: synthetic lifecycle markers (--- sandbox started ---/--- sandbox stopped ---) plus diagnostic lines fromruntime.log/kernel.logwhen--source systemis requested.
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), orexited(the preserved terminal sample of a stopped or crashed sandbox).CPU: vCPU-seconds per wall-second over the allocation, e.g.0.80 / 2cmeans 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;exitedrows show cumulative totals instead.
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.