$ man Get started

This page takes you from a fresh install to an agent running in your first sandbox. It takes about ten minutes, most of which is the first bootstrap.

1. First run: the machine-level setup#

$ msbctl

The first time msbctl runs on a machine with nothing configured, it offers a short walk-through. Each step is optional, and msbctl setup returns to any of them later:

• Git identities: the names and emails a sandbox can commit as, and optionally an SSH key to sign with. They're applied inside the guest with git config --system, so a repo's own identity still wins.
• Claude login: a long-lived token from claude setup-token, stored in ~/.config/msb/secrets/global.env (mode 0600). Sandboxes get a placeholder for it; the real token never enters a VM.
• Your network: egress groups for your own machines, such as a Git server or a package mirror on your LAN.
• New-sandbox defaults: where projects live, the default cpus and memory, which identity to use.

2. Register a project#

$ msbctl add myproject

A bare name resolves under your workspaces folder (~/workspaces by default), and the folder is created if it's missing. A path that states its location is taken as written: /srv/thing, ~/src/thing, ./thing.

The wizard then asks, in order:

1. Sandbox name: lowercase letters, digits and dashes. It defaults to the folder name.
2. GitHub repo: detected from the checkout's origin. If the folder is empty, it offers to clone the repo into a subfolder over SSH.
3. Git identity and SSH keys: which keys from your host agent this sandbox may use. Nothing is ticked by default.
4. Features and agents: what the project needs, not raw egress rules. Ticking python brings the PyPI egress group and the toolchain packages. Features are pre-ticked from the repo's languages on GitHub.
5. Resources and disks: cpus, memory, the root disk size and, for podman, a container disk.
6. Package caches, extra folders and secrets: all optional.
7. Image: offered pinned by digest, so a moving tag can't change the sandbox underneath you.
8. GitHub token: a fine-grained PAT for this one repository, read straight into a 0600 file. It's never echoed and never on a command line.

Nothing is started yet. The wizard writes three things:

The GitHub token#

GitHub has no API for creating fine-grained tokens, so this one step is manual, once per project. Create one at https://github.com/settings/personal-access-tokens/new with exactly:

Inside the sandbox, GH_TOKEN is a placeholder. The real value is swapped in on the host, in request headers only, for github.com and api.github.com. git push over SSH doesn't use it at all; that goes through the filtered SSH agent.

3. Start it#

$ msbctl start myproject

The first start creates the VM and runs the bootstrap inside it, once. That installs the base packages, node, gh, Claude Code and whatever the features asked for. It takes a few minutes. The bootstrap deliberately doesn't stop at the first failure: it reports every step that failed together at the end, so a missing egress rule shows up in one pass rather than one round trip at a time.

Later starts take seconds: the VM keeps its state between stop and start.

4. Work in it#

$ cd ~/workspaces/myproject
$ msbctl shell

Inside a registered project folder you can leave the sandbox name out (see Everyday use). The shell starts in /work, which is your project folder, shared from the host. Files the guest writes there belong to you on the host.

Run the agent:

$ claude

It's already logged in through the placeholder token, already has the central CLAUDE.md, and can push to GitHub through the filtered SSH agent.

5. Stop it#

$ msbctl stop

Stopping keeps everything: installed packages, the Claude state, your files. An idle running sandbox costs about 300 MB, so leaving a few running is cheap.

Where next#

• Everyday use: the picker, exec, and the current-folder shortcuts.
• Network & egress: what to do when something is refused.
• Credentials & SSH: more tokens, key selection, commit signing.