112 lines
5.6 KiB
Markdown
112 lines
5.6 KiB
Markdown
# 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<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
|
|
```
|
|
|
|
```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
|