# wsbx Linux microVMs for coding agents on Apple Silicon macOS. Each sandbox is a real VM (Virtualization.framework via [vfkit]) booted from any OCI image with a Kata Containers kernel. ## Install ```sh brew install vfkit e2fsprogs curl -fsSL https://git.nhaiden.io/niklas/woiken-sandboxes/raw/branch/main/install.sh | sh ``` Installs the latest release to `~/.local/bin` (sha256-checked). `WSBX_VERSION=v0.2.1` pins a release, `WSBX_INSTALL_DIR` changes the target. From source: `brew install go && cargo install --path .`. ## Usage ```sh wsbx claude | codex | gemini | pi # agent in a VM, current dir mounted at the same path wsbx run -w . ubuntu -- make test # any image, one-off command, exit code propagated wsbx run -p 8000 alpine # host localhost:8000 reachable inside the VM wsbx exec NAME [-- cmd] # shell/command in a running sandbox (-u root) wsbx forward NAME 3000 8080:80 # guest localhost ports on the Mac's localhost wsbx code NAME [--desktop] # VS Code in the browser, or desktop via Remote-SSH (ssh NAME.wsbx) wsbx ps [-f] # status, CPU, memory, I/O, disk wsbx rm NAME... [--disk] | wsbx pull IMAGE | wsbx gc | wsbx kernel [--update] ``` Run options: `--name --workspace --cpus --memory --disk --env K[=V] -p PORT --fresh --pull --kernel`. Agents: `--keys` forwards API keys; `pi` mirrors the host's pi version and config (`--pi-auth` adds `auth.json`). ## Architecture ```mermaid flowchart LR reg[("OCI registry")] subgraph host["macOS host"] cli["wsbx"] img[("~/.wsbx/images
flattened rootfs.tar")] sbx[("~/.wsbx/sandboxes/NAME
disk.img · meta.json")] share["share/
init · run.sh · guest helper"] ws["workspace"] socks["exec.sock · pPORT.sock"] end subgraph vm["Linux microVM"] init["busybox init (PID 1)"] run["run.sh (root)"] cmd["agent / command
(image user)"] helper["guest helper"] end reg -->|"verify, flatten"| cli --> img cli -->|"spawns vfkit"| vm img -.->|"virtio-blk ro, first boot only"| init sbx -->|"virtio-blk /"| init share -->|"virtio-fs /.wsbx/host"| init init --> run --> cmd run --> helper ws -->|"virtio-fs, same path"| cmd socks <-->|"vsock"| helper ``` ```mermaid sequenceDiagram participant H as wsbx (host) participant V as vfkit participant G as guest H->>H: pull image (cache, tags re-resolved after 24 h) H->>H: first start: write meta.json, mke2fs disk seeded with busybox + stub init H->>H: recreate share/ (init, run.sh, guest helper) H->>V: boot kernel, disk, share, workspace, vsock V->>G: stub init mounts share, execs current init G->>G: first boot: untar image from read-only disk G->>G: run.sh: env, mounts, start helper, drop to image user G-->>H: exit code via share/exit, then poweroff ``` - **One process per VM.** The VM lives as long as its command; the exit code comes back through the share. - **Persistent disk, fresh plumbing.** `disk.img` (sparse ext4) keeps the guest's state between runs; init, `run.sh` and the guest helper are rewritten into the share on every start, so upgrading wsbx upgrades existing sandboxes. - **Own OCI client.** Anonymous pulls of linux/arm64 images, layers flattened on the host (whiteouts applied), cached by digest. No Docker needed. - **No host network exposure.** `exec`, `forward`, `code` and `-p` tunnels all run over vsock through unix sockets in the sandbox dir; host-side listeners bind loopback only. Guest egress is vfkit NAT. - **Code layout.** Host: `src/*.rs`. Guest helper (exec, port forwarding, SSH for VS Code): `guest/*.go`, cross-compiled by `build.rs` and embedded in the binary. Design notes: `PLAN.md`. ## Security model The VM is the boundary. The guest, including a prompt-injected agent or a malicious image, is assumed hostile. - **Control share**: guest-writable, so it's recreated empty on every start and deleted after exit. Guest outputs are read only as small regular files; persistent state lives in host-only `meta.json`. - **Image**: env keys must be shell identifiers; the command runs as the image's user. - **vfkit arguments**: paths with `,` `"` or control characters are refused. Workspaces overlapping `~/.wsbx` are refused. - **Registry**: references validated, digest pins enforced, every blob/manifest sha256-verified, auth realms https-only. Connections to loopback/private/link-local addresses are refused, including auth realms, redirects and IPv6 forms (NAT64, 6to4). A registry is local only if named `localhost` or a private IP literal; use the IP for LAN registries. 30 s network timeouts. - **Guest base**: busybox (PID 1) is pinned by digest; the kernel is sha256-checked against the Kata release. - **exec**: the guest helper accepts sessions only from the host's vsock CID, not from guest processes. - **code**: the in-guest SSH server is reachable only through `wsbx exec`, allows no `-R` or agent forwarding. - **pi config**: allowlisted files only; symlinks only into `~/.pi/agent` or `~/.agents/skills`, capped at 256 MB. Remaining risks: - The workspace is read-write: a guest can plant files that later run on the host (`.git/hooks`, `.envrc`, package scripts). - Egress is unrestricted, so anything in the VM (`--keys`, pi's `models.json`, `--pi-auth`) can be exfiltrated. - Browsers share `localhost` cookies across ports: a page served via `forward` or `code` can read your other localhost apps' cookies. Desktop VS Code also auto-forwards guest ports (`remote.autoForwardPorts`). - Image layers are unpacked on the host, so a decompression bomb can fill the disk. - A kernel panic before the root disk mounts restart-loops; later panics stop the VM. [vfkit]: https://github.com/crc-org/vfkit