Skip to main content
Use the short form, such as msb run. msb sandbox run and msb sbx run accept the same arguments. Aliases include ls, ps, rm, cp, and mod. See SSH, Snapshots, and CLI management for other commands.

msb run

Create a sandbox and run its image command. Arguments after -- replace CMD but preserve ENTRYPOINT. Unnamed sandboxes are removed when the command finishes; named sandboxes persist. Piped input is forwarded to the command; use --no-stdin to leave it for the calling script.
--entrypoint accepts one executable, not a shell command string. Put each argument after the image and --; microsandbox preserves those argument boundaries. Invoke a shell explicitly, as above, when the command uses shell syntax such as ;, pipes, or redirects. Common flags: Use msb run --help for the full flag list. Pass configuration files explicitly. Files merge left to right; explicit CLI arguments override them. See Configuration.

Flat OCI rootfs

Use a complete ext4 root instead of the default layered root. Each sandbox gets a private copy of the cached base.
Pre-pulling is optional. See clone strategies for copy behavior and host requirements. Flat roots support pre-boot patches and local snapshots. Patches change only the private disk; snapshots preserve its layout. Set sandbox_defaults.oci.root_disk to use flat roots by default. See storage optimization.

Published ports

Ports bind to 127.0.0.1 by default. Use an explicit address to expose them beyond localhost. Windows may prompt for firewall access. --port (or -p) accepts inclusive, equal-length host and guest ranges, paired in ascending order:
The second mapping forwards host ports 8000, 8001, and 8002 to guest ports 80, 81, and 82. TCP is the default; /udp selects UDP. IPv6 bind addresses require brackets, for example [::1]:8000-8002:80-82. Range endpoints must be from 1 to 65535; reversed ranges and unequal lengths are rejected. The same syntax works with run, create, restore, and fork, and in configuration-file ports lists.
Ranges expand into individual mappings. The UDP example opens 1,025 host sockets; large ranges require enough host socket/file-descriptor capacity and consume resources per port. A range does not reserve ports as one atomic block; existing per-port listener startup and error reporting apply.--max-inbound-tcp-connections limits active connections across published TCP ports; 0 means unlimited. Omission uses the runtime default: unlimited in 0.7.9+, or 256 in older versions. Unsupported overrides fail with an upgrade-required error. This limit is separate from the listener queue. See connection limits.
Each published TCP port’s host listener queues up to 1,024 connections that the runtime has not yet accepted. Connections that arrive while the queue is full never reach the sandbox. A burst larger than the queue can fail at the proxy. For example, a reverse proxy may open one upstream connection per request for a page that loads many assets at once. Set --tcp-accept-queue-size to change the depth for every published TCP port of the sandbox:
The host kernel caps the queue at its own limit: net.core.somaxconn on Linux (4,096 by default) and kern.ipc.somaxconn on macOS (128 by default). A larger value is accepted but has no further effect until that limit is raised. The setting requires a runtime that supports it; the SDK refuses to launch an older runtime rather than silently ignoring it.

VSock

Use the repeatable --vsock HOST_PATH:PORT[/stream|/dgram] flag to expose a host Unix socket or local Windows named pipe on guest host CID 2. Stream is the default. Datagram routes preserve message boundaries and are unavailable on Windows. See Host sockets for guest connection details, limits, and SDK examples.

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.
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. NAT64 destinations inside the well-known 64:ff9b::/96 prefix are classified by their embedded IPv4 address, so a public-only policy still blocks translated private, loopback, link-local, and metadata addresses. If your environment uses another routed NAT64 prefix, add it with repeatable --net-nat64-prefix <ipv6-cidr> entries. Only IPv6 /96 prefixes are accepted.

Outbound proxy

Use --proxy with msb run or msb create to configure one HTTP CONNECT, SOCKS4, or SOCKS5 proxy:
HTTP CONNECT and SOCKS4 support TCP; SOCKS5 also supports non-DNS UDP. HTTP CONNECT and SOCKS5 authentication each require both flags and read the password from the host environment at startup. Pass --http-connect-username "" when the proxy authenticates with a token and no username. Proxy URLs cannot contain credentials, paths, queries, or fragments. See Proxies.

Network rule syntax

--net-rule takes one or more comma-separated rule tokens. The token grammar is:
Targets Quote rule values so the shell does not interpret wildcard characters. Common compositions

msb create

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

msb snap restore

Restore into a new sandbox. Disk snapshots boot fresh; full snapshots resume execution. Cloud supports disk restore. Use msb exec to run new commands. The existing msb restore, msb sandbox restore, and msb sbx restore forms accept the same flags.
Progress is shown by default. Memory preparation has no fixed timeout and does not consume the activation timeout. Full restore must keep captured CPU and memory settings and cannot apply a guest security profile. Use --disk-only to change them. Network flags replace the destination policy. --net-rule requires --net-default or --no-net; omitting all policy flags keeps configured defaults. Restore requires a new name and does not accept a startup command. Supply host resources explicitly when restoring or forking. -v /host/path:/guest/path maps a host directory; -v /guest/path selects a private captured disk. -p HOST:GUEST publishes a new listener. --vsock HOST_PATH:PORT exposes a host service for clients to reconnect to. Restore requires recorded external filesystems and, for full restores, additional disks. --allow-missing-resources permits unavailable resources, but access can fail or make a guest filesystem read-only. Root and owned snapshot storage must still be complete.
Full restores warn about unavailable resources even with --quiet; disk restores omit unmapped mounts without warnings. Cached guest memory may remain readable, but device I/O fails and can abort filesystem journals.--external-mount-policy relaxed tolerates supported stale-object mismatches; it does not allow missing backing. --dangerously-inherit-resources reuses validated source-local bindings. Direct forks retain their existing unavailable-resource behavior. See external mounts.

msb start

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

msb stop

Stop waits until shutdown completes, with no default timeout. A timeout fails without killing; a dispatched stop may still finish later. Zero expires before dispatch. Paused or unreachable sandboxes return an error; resume or force-stop them. --force kills immediately and may lose unsynced writes.

msb pause / resume

Suspend a resident sandbox without creating a snapshot, then resume it. These operations also accept the top-level msb pause and msb resume forms.
pause --guest-flush required flushes captured persistent filesystems before pausing, so a later disk snapshot can reuse that boundary without resuming. The default auto and explicit skip omit optional writeback; mandatory storage barriers remain. An already-paused VM without the required flush fails rather than resuming implicitly. resume has no flush option. See guest filesystem flush.

msb fork

msb branch remains a deprecated alias. Use fork in new scripts. Create a local child from running or paused execution without saving a snapshot. Memory is shared through copy-on-write; each child’s memory writes stay private.
Use --names to capture once and start several independent children from the same state:
Both fork forms accept the guest writeback policy through --guest-flush. Auto and skip preserve dirty memory without flushing root or owned block filesystems; required adds writeback. Host-backed directory synchronization and host disk barriers remain in effect.
Volume, port, TCP accept queue size, user, vsock, inheritance, and mount-policy flags match restore. A fork cannot add a new block device. --mount-disk only rebinds a captured disk, such as a named disk volume, at DEST to a host image consistent with the captured state. Images are attached directly, so batch forks must not share a writable image. See fork disk bindings for details. Batch forking captures once. Results follow input order; failed children produce a nonzero exit status without removing successful ones.

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 --force kills immediately. Otherwise --timeout bounds graceful completion; expiry fails without killing or starting a replacement. Unlike standalone Stop, Restart retains its explicit default budget of ten seconds.

msb wait

Wait for an existing sandbox to reach Stopped or Crashed. Also available as msb sandbox wait and msb sbx wait. Use msb run --name worker --detach … to keep the sandbox available for a later msb wait; unnamed runs are removed when they finish.
The timeout covers lookup and waiting. It returns an error without stopping the sandbox. Missing sandboxes return an error; stopped or crashed sandboxes return immediately. A successful wait means the sandbox stopped or crashed, not that its workload succeeded.
Text output shows the sandbox name and status. JSON includes name, status, terminal, exit_code, signal, observed_at, and source. Exit codes and signals are currently unavailable (null); observed_at records when the terminal state was observed.

msb ping

Check whether running sandboxes respond. Add --touch to refresh the idle timer on success.

msb touch

Refresh the idle timer for one or more running sandboxes.

msb modify

msb mod is a shorter alias for 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.
Like create/run, modify accepts -c/--cpus, -m/--memory, -e/--env, and -w/--workdir. Set --max-cpus and --max-memory at creation to leave room for live growth. They default to the initial CPU and memory allocation; increasing the ceilings requires a restart. Resize can take time. The output and JSON resize_status report each resource’s resize state. With guest-refused, the host still enforces the new limit. 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 reads the same-named host environment variable; inline values are rejected. Options are query, body, no-headers, headers=[FIELD,...] (substitute only in those header fields; headers=* restores all headers, * cannot be combined with named fields, and headers= cannot be combined with no-headers), and passthrough=HOST or passthrough=[HOST,...]. Restrict headers to the credential header the API reads, since substituting in every header lets a reflecting endpoint return the secret to the guest. Without query, body, no-headers, or headers=, modify keeps the secret’s current substitution rule. Any of them replaces the whole rule, and unstated locations reset to defaults, so query alone re-enables every header. Repeated declarations merge. See secret updates.
See live changes for resize behavior. Use msb modify --help for the full flag list.

Compaction

Merge sealed layers in the local root and owned disks. Run separately from configuration changes; the sandbox must be running or fully stopped.
The writable layer is excluded. Fewer than two sealed layers or no eligible disks means no change. See compaction recovery before applying.

msb exec

Execute a command inside a sandbox. An already-running sandbox stays running. Stopped or crashed sandboxes start temporarily and stop again before the command returns, including after execution errors. Invalid environment, resource-limit, or timeout arguments fail before startup.
Use --detach to keep a command running after you disconnect. It requires a running local sandbox and prints a job ID after startup is confirmed. See background jobs for logs, reattachment, and lifecycle details. Resource limits apply inside the guest before switching to --user, so non-root commands can use explicitly raised hard limits. The override affects only that command and its descendants; it does not change the guest agent’s limits or the host’s limits. For example, allow a command to lock up to 64 MiB for registered io_uring buffers:
The CLI auto-detects whether stdin is a terminal. When interactive, msb exec uses attach mode (TTY, line editing). When piped, it forwards input while the command runs and captures output until the command exits. Use --no-tty to force captured, non-interactive execution even from a terminal; terminal input is not forwarded in that mode.
Use --stream for an ongoing conversation with a guest process, such as an ACP agent. It returns output as it arrives instead of waiting for command completion. Piped commands can exit or time out while the host input pipe is still open. Commands that read until EOF, such as cat, still need their input closed to finish normally. Use --no-stdin to leave input available to the calling script and give the guest immediate EOF:
Combine --no-stdin with --stream when you want live output without forwarding input. Omit --no-stdin for ACP agents, which need input from the IDE.

msb copy

Copy files between the host and a sandbox.
Supports host-to-sandbox, sandbox-to-host, and copies within or between sandboxes. Stopped sandboxes start temporarily, as with msb exec. Alias: msb cp.

msb logs

Read output from running or stopped local sandboxes. On cloud, use --follow to stream a running sandbox; historical reads and time filters are unavailable.
The s field in JSON output identifies the source:
If startup failed, logs include the failure stage and a troubleshooting hint.

msb list

List all stored sandboxes.

msb status

Show sandbox status with process details.
CPUS and MEM show current allocation / maximum resize capacity. For measured usage, use msb metrics.

msb metrics

Show live CPU, memory, disk, network, and optional upper disk metrics for running sandboxes.
Limits reflect live resizes. One-shot output samples twice to calculate rates. JSON and follow output keep cumulative counters and include state and cpus.

msb inspect

Show detailed configuration and status.

msb remove

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.
By default, each run reuses the same sandbox, keeping its files and mounts. Add --tmp to create a fresh sandbox each time and delete it on exit. Files in mounted host folders are kept. To mount the folder you run the command from:
Run project-shell from any folder to open it at /workspace inside the sandbox. Keep ./ as written so the path is resolved on each run, rather than passing a full path during installation.

msb uninstall

Remove an installed sandbox command.