Install
Requirements#
| What | Why |
|---|---|
Linux with /dev/kvm | microsandbox is a libkrun microVM runtime, so this runs on a host, never inside a container |
msb on PATH | the runtime itself. Developed against 0.7.6, re-checked on 0.7.7 |
| Python 3.11+ | msbctl uses only the standard library (tomllib needs 3.11). Nothing to pip install, ever |
git | project detection, cloning |
fzf (optional) | the full-screen menu and the picker; without it you get numbered prompts |
| a terminal emulator (optional) | for the desktop entry: konsole, alacritty, foot, gnome-terminal and xterm are detected |
One-line install#
$ curl -fsSL https://github.com/runoverlabs/sandbox-manager/releases/latest/download/get.sh | shget.sh finds the latest release, downloads it, verifies its sha256 against the checksums published with it, and runs the installer inside it. If the checksum doesn't match, nothing is installed. If an authenticated gh is on PATH, it also checks the tarball's build provenance (see verifying a release) and refuses to install if that check fails.
To pin a release or pass installer options:
$ curl -fsSL .../get.sh | sh -s -- --version v0.2.0 # a specific release
$ curl -fsSL .../get.sh | sh -s -- --prefix ~/tools # flags after -- go to install.shinstall.sh option | Effect |
|---|---|
--prefix DIR | where versions are kept (default ~/.local/share/msb-manager) |
--bin-dir DIR | where msbctl and msb-picker are linked (default ~/.local/bin) |
--no-desktop | skip the "Sandboxes" desktop entry |
--uninstall [--yes] | remove what the installer put there; your config and sandboxes stay |
What a package install does#
The release is copied to ~/.local/share/msb-manager/versions/<version>/, current points at it, and ~/.local/bin/msbctl and msb-picker link through current. An upgrade is therefore one atomic switch, and the previous version stays around for rolling back. The installed tree is real files only: the installer refuses a release that contains symlinks.
$ msbctl self-update # the latest release
$ msbctl self-update --version v0.2.0 # a specific one
$ ~/.local/share/msb-manager/current/install.sh --uninstallVerifying a release#
A checksum published next to a tarball only proves the download wasn't damaged: anyone who could replace the tarball could replace the checksum too. So each release is also attested: a Sigstore-signed statement, made by this repository's release workflow, of exactly which commit built which file. You can check it yourself:
$ gh attestation verify msb-manager-0.2.0.tar.gz --repo runoverlabs/sandbox-manager \
--signer-workflow runoverlabs/sandbox-manager/.github/workflows/release.ymlget.sh and msbctl self-update run this check automatically when gh is logged in, refuse to install if it fails, and tell you plainly when only the checksum could be checked. Set MSB_MANAGER_SKIP_ATTEST=1 to skip it.
From a checkout (development)#
$ git clone https://github.com/runoverlabs/sandbox-manager msb-manager
$ cd msb-manager
$ ./install.sh # --dev is implied inside a git checkoutDev mode symlinks the two commands into the checkout, so git pull updates the tool with no reinstall. msbctl self-update tells you to git pull instead. Everything else works the same in both modes.
What is yours, and what ships#
The installer seeds two files that you own. They're real files, never links into the installed tree, and no install or upgrade overwrites them:
~/.config/msb/config.toml: your overrides on top of the shippeddefaults.toml, such as egress groups, version pins and default resources. Keep it short;msbctl configprints the merged result and where each value came from. See the configuration reference.~/.config/msb/CLAUDE.local.md: your additions to theCLAUDE.mdevery sandbox gets. On each start msb-manager's own text and yours are put together into~/.local/state/msb/profile/, and that's what sandboxes see, read-only.
defaults.toml itself ships with msb-manager and is read straight from the installed tree, so an upgrade updates it. Never edit it; put your changes in config.toml.
Next: Get started.