$ man Commands

msbctl --help and msbctl <command> --help are always current. This page explains them.

Naming the sandbox#

• name: optional. Inside a registered project folder it defaults to that folder's sandbox. Elsewhere, it's required.
• name…: optional and repeatable. None, or ., means the current folder's sandbox; several names act on each in turn, and every failure is reported, not just the first.
• name|.: required, because another argument follows it. . is the shorthand for the current folder's sandbox.

See Everyday use for the rules behind this.

Registering and inspecting#

msbctl add#

msbctl add [dir]

Register a project with the setup wizard. Nothing is started. A bare name resolves under your workspaces folder and is created if missing; a path starting with /, ~, ./ or ../ is taken as written. Without an argument it asks, defaulting to the current directory. See Get started.

msbctl ls#

msbctl ls [--refresh] [--porcelain] [--picker]

One line per sandbox: name, state, project, pending updates, autostart. --refresh checks upstream versions first. --porcelain prints tab-separated fields for scripts; --picker is the format msb-picker reads.

msbctl status#

msbctl status [--quick]

One block per sandbox, as shown beside the menu: state, RAM and CPU, identity, image, folder. --quick skips reading figures from inside each guest.

msbctl show#

msbctl show [name]

Everything about one sandbox: resources, disks, extra folders, installed versions, environment, every egress rule in the order it's emitted, and the identity, keys and secrets bound to it.

msbctl config#

msbctl config

The merged configuration (defaults.toml plus your config.toml), with where each value comes from.

msbctl entry#

msbctl entry [name]

Open the sandbox's registry entry (~/.config/msb/sandboxes/<name>.toml) in a terminal editor.

Lifecycle#

msbctl start#

msbctl start [name…]

Start a stopped sandbox, or create it if it doesn't exist yet. Creating runs the bootstrap, once.

msbctl stop#

msbctl stop [name…]

Stop it. Everything is kept.

msbctl rebuild#

msbctl rebuild [name…]

Destroy and recreate. Needed after changing anything fixed at create time: egress rules, mounts, the image, environment variables. Your files, the Claude state, package caches and container images survive; packages installed by hand don't. Doesn't ask first.

msbctl purge#

msbctl purge [name…] [-y]

Destroy the sandbox and deregister it: the VM, its Claude state, its disk volumes, its secrets file and its registry entry. Your project folder is never touched. Lists exactly what it will delete, and asks once per sandbox unless -y is given. Remember to revoke its GitHub token too.

msbctl rename#

msbctl rename name|. new-name [-y]

Give a sandbox a new name. msb can't rename a VM, so this recreates it, like a rebuild; settings, secrets, Claude state, caches and container images all move with it. See Advanced usage.

msbctl move#

msbctl move name|. dir [--rebuild]

Point a sandbox at another project folder. dir is read as it is for add. Offers to copy .msb/ across if the new folder lacks it, and re-detects the GitHub repo. The folder is mounted at create time, so this needs a rebuild: --rebuild does it now.

msbctl resize#

msbctl resize [name] [--cpus N] [--memory SIZE] [--root-disk SIZE] [-y]

Change resources and keep the sandbox's state. cpus and memory need a restart (asks first unless -y is given); the root disk grows live and can't shrink. With no options it asks.

msbctl reclaim#

msbctl reclaim [name…]

Give the guest's page cache back to the host. Harmless, and takes about a second.

Working inside#

msbctl shell#

msbctl shell [name]

An interactive login shell, with the SSH agent wired up, starting in the subfolder of /work that matches your current directory. Starts a stopped sandbox; never creates one.

msbctl exec#

msbctl exec name|. [--] command…
msbctl exec -- command…

Run one command in the sandbox, like shell but non-interactive. exec -- cmd is the short form for the current folder's sandbox.

msbctl code#

msbctl code [name]

Open your editor on the project folder, on the host: $MSB_EDITOR, default codium.

Changing a sandbox#

msbctl edit#

msbctl edit [name]

The setup wizard as a menu of sections, run one at a time against an existing sandbox: name and folder, features and agents, resources, package caches, container storage, extra folders, egress rules, SSH keys, GitHub token, secrets, identity and autostart, or the files themselves in your editor. Applies what it can immediately and offers one rebuild at the end for the rest.

msbctl allow#

msbctl allow name|. target… [--rebuild]

Add egress rules. Each target is host (HTTPS, :443), host:port (TCP), or a full rule such as allow@10.0.0.5:tcp:5432. Written to the project's extra_rules. See Adding a host.

msbctl observe#

msbctl observe name|. [report|on|off] [--rebuild] [-y]

on stops blocking and records every host the sandbox reaches; report (the default) reads that record back and prints the msbctl allow line for what no rule covers; off restores deny-by-default. Turning it on asks first unless -y is given. See Observe mode.

msbctl mount#

msbctl mount name|. SRC[:DEST][:ro|rw] [--rw] [--rebuild]

Add an extra host folder. DEST defaults to /mnt/<folder name>; read-only unless rw or --rw is given. Needs a rebuild.

msbctl secret#

msbctl secret add name|.
msbctl secret ls  name|.
msbctl secret rm  name|. VAR

Tokens the sandbox can use but never see. add offers the presets or takes your own binding. See Credentials & SSH.

msbctl keys#

msbctl keys [name] [--all]

Choose which keys from your SSH agent (and ~/.ssh) the sandbox can list and sign with. Takes effect immediately. --all removes the restriction.

msbctl cache#

msbctl cache name|. [ls|clear] [key]

Show the package-cache disks, or empty one (or all of them, if no key is given). See Package caches.

msbctl update#

msbctl update [name…] [-c component…]

Update components in place, without a rebuild. Components: claude (the default), gh, gitleaks, bun, apt. Versions installed this way are recorded so a rebuild reproduces them. Run msbctl ls --refresh first for gh, gitleaks and bun.

The machine and msb-manager itself#

msbctl setup#

msbctl setup [--welcome]

Your machine-level settings as a menu: git identities, Claude login, your network, new-sandbox defaults, or the config file itself. --welcome runs the first-time walk-through.

msbctl self-update#

msbctl self-update [--version vX.Y.Z]

Upgrade a packaged install to the latest release, or a given one, verifying it the same way the installer does. In a git checkout it tells you to git pull.

Environment variables#