$ man Overview

msb-manager runs coding agents against your real repositories inside microsandbox microVMs, without giving them your network or your tokens. One sandbox per project, managed by a single command, msbctl, and a picker.

$ msbctl add myproject          # register it: a short wizard
$ msbctl start myproject        # create the VM and bootstrap it, once
$ cd ~/workspaces/myproject
$ msbctl shell                  # a shell in this folder's sandbox; run claude there

What you get#

Deny-by-default egress, per host and per port. A sandbox reaches the hosts its project needs and nothing else. Egress rules come in named groups (github, npm, python, go, …) that a project picks from. A sandbox that needs SSH to one machine gets that port on that machine, not the whole machine.

Tokens never enter the VM. Inside the sandbox, $GH_TOKEN holds a placeholder. The real value is swapped in on the host, in request headers only, and only for the hosts it was issued for. gh api user works; the token can't be read from inside the sandbox, so it can't leak from there either.

SSH without keys in the guest. The sandbox talks to a per-sandbox filter in front of your SSH agent. It can list and sign with only the keys you picked, which lets it push over SSH and sign commits. The private keys never cross over.

One central CLAUDE.md. Every sandbox gets msb-manager's own instructions plus your additions, copied in on each start from a read-only mount. Each sandbox has its own ~/.claude, so none of them holds your real Claude credentials or another project's transcripts.

Config that travels with the repo. Egress groups, packages and resource limits live in the project's .msb/ and are committed with it. Host paths and tokens stay in ~/.config/msb/ on your machine.

No dependencies. msbctl is one Python file that uses only the standard library, plus the msb binary. Nothing from pip, nothing to break after a year of not being touched.

How it fits together#

host                                          microVM (one per project)
──────────────────────────────────            ─────────────────────────────────
msbctl ── creates/starts ───────────────────▶ /work      ← your project folder
~/.config/msb/    your config, tokens         ~/.claude  ← its own state
ssh-agent ◀── filter (only picked keys) ◀──── git push / commit signing
msb egress: rules + secret substitution ◀──── every outbound connection
│
└─▶ the internet, only where a rule allows

The VM sees your project at /work, with your own file ownership, so whatever the agent writes is yours on the host. Everything else stays on the host: your config, your tokens and your keys.

Where to go next#

• New here? Install, then Get started.
• Already running a sandbox? Everyday use covers the commands you'll type every day.
• Something refused a connection? Read Network & egress, then Troubleshooting.
• Looking up a flag? See the command reference and the configuration reference.