Files

5.6 KiB

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.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.