v0.2.2
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
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
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
flowchart LR
reg[("OCI registry")]
subgraph host["macOS host"]
cli["wsbx"]
img[("~/.wsbx/images<br/>flattened rootfs.tar")]
sbx[("~/.wsbx/sandboxes/NAME<br/>disk.img · meta.json")]
share["share/<br/>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<br/>(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
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.shand 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,codeand-ptunnels 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 bybuild.rsand 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~/.wsbxare 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
localhostor 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-Ror agent forwarding. - pi config: allowlisted files only; symlinks only into
~/.pi/agentor~/.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'smodels.json,--pi-auth) can be exfiltrated. - Browsers share
localhostcookies across ports: a page served viaforwardorcodecan 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.