install script, slimmer README with architecture diagrams

This commit is contained in:
2026-10-22 21:02:37 +02:00
parent 7ca42b0e9f
commit 5f06c955cb
2 changed files with 121 additions and 78 deletions
+92 -78
View File
@@ -1,97 +1,111 @@
# wsbx
Docker-Sandboxes-style microVMs on Apple Silicon macOS. Each sandbox is a real Linux VM
(Virtualization.framework via [vfkit]), booted from any OCI image with a Kata Containers kernel.
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 go # go: builds the static guest tunnel helper
cargo install --path . # or grab wsbx-*-darwin-arm64.tar.gz from a release (push a v* tag to build one)
wsbx claude # Claude Code in a VM, current dir mounted at the same path
wsbx codex | wsbx gemini # other agents (Docker's sandbox-templates images)
wsbx pi # pi coding agent, same version + config as on the host
wsbx run alpine # bare VM, interactive shell
wsbx run -w . ubuntu -- make test # one-off command, exit code propagated
wsbx run -p 8000 alpine # host's localhost:8000 reachable as localhost:8000 in the VM
wsbx exec NAME # shell in a running sandbox (alias: sh), as the image's user
wsbx exec -u root NAME -- apk add git # command, exit code propagated
wsbx forward NAME 3000 8080:80 # sandbox's localhost:3000 on the Mac's localhost:3000 (until Ctrl-C; alias fwd)
wsbx code NAME # VS Code in the browser, running in the sandbox (until Ctrl-C)
wsbx code NAME --desktop # desktop VS Code via Remote-SSH; also: ssh NAME.wsbx
wsbx ps # sandboxes: status, CPU, memory, net/block I/O, PIDs, disk, image (alias: ls)
wsbx ps -f # same, refreshed every second like `docker stats`
wsbx rm NAME... # delete stopped sandboxes; --disk deletes only the disk (fresh on next start)
wsbx pull IMAGE
wsbx gc # delete cached images no sandbox uses
wsbx kernel [--update | --version TAG] # latest Kata release by default, sha256-verified
brew install vfkit e2fsprogs
curl -fsSL https://git.nhaiden.io/niklas/woiken-sandboxes/raw/branch/main/install.sh | sh
```
Defaults for `--cpus`/`--memory` come from the host (half the cores, a quarter of RAM up to 8 GiB). Image tags
are re-resolved after 24 h (cached copy used when offline); the superseded image is deleted automatically. `WSBX_KATA_VERSION` pins the kernel release.
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 .`.
Options: `--name --workspace --cpus --memory --disk --env K[=V] --host-port/-p PORT --fresh --pull --kernel`.
## Usage
**exec**: host → vfkit unix socket (`exec.sock`) → vsock → guest helper. It runs in the workspace dir with the sandbox's env.
You get a pty (with resize) when stdin and stdout are terminals, plain pipes otherwise, so `wsbx exec x -- cat f > out` is byte-exact.
```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]
```
**forward**: host `127.0.0.1:HOSTPORT` → `exec.sock` → vsock → guest helper → guest `localhost:PORT`, one exec-style session
per connection. Works for services bound only to the guest's loopback, on running sandboxes, no restart. `0:PORT` picks a free host port.
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`).
**code**: browser mode fetches the official VS Code CLI into the sandbox (`~/.wsbx-vscode`, needs internet in the VM) and runs
`code serve-web` on the guest's loopback, forwarded like `forward` to a random host port behind a random connection token.
The CLI downloads the matching server on first open (glibc or Alpine images). `--desktop` writes `~/.wsbx/ssh_config` (a `NAME.wsbx`
host per sandbox) and adds an `Include` for it at the top of `~/.ssh/config` once. ssh reaches an SSH server in the guest helper through `wsbx exec`
(`ProxyCommand`): no port, no keys, you're the image user. Remote-SSH then installs its server in the VM as usual.
If the VM was killed mid-download and the server won't start, delete `~/.vscode/cli/serve-web` (browser) or `~/.vscode-server` (desktop) in the sandbox.
Both need a sandbox started by this wsbx version (the guest helper ships with each start).
## Architecture
**Host tunnel** (`-p PORT`): guest `localhost:PORT` → vsock → vfkit → unix socket → host `localhost:PORT`.
Nothing listens on a host network interface, and only the listed ports are reachable.
```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
```
**pi**: installs `@earendil-works/pi-coding-agent` at the host's `pi --version` (reinstalls when it changes).
On every start it copies these from `~/.pi/agent` with symlinks resolved: settings, models, keybindings, mcp, AGENTS/CLAUDE/SYSTEM md files,
extensions, skills, prompts, themes. They're linked into the guest's own `~/.pi/agent`, so host edits
win and in-VM edits are discarded. `npm/`, `bin/` (macOS binaries) and sessions stay in the VM. `auth.json` is only
copied with `--pi-auth`. Local `baseUrl`s in `models.json` (127.0.0.1/localhost) are tunneled automatically.
Agent API keys (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, …) are only forwarded with `--keys`. Code in the VM can read them.
Sandboxes persist per name (disk under `~/.wsbx/sandboxes`); `--fresh` rebuilds. See `PLAN.md` for design.
```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
```
[vfkit]: https://github.com/crc-org/vfkit
- **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.
The VM is the boundary. The guest, including a prompt-injected agent or a malicious image, is assumed hostile.
- **Control share** (`/.wsbx/host`): the guest can write to it, so it's recreated empty on every start while the VM is stopped and
deleted after exit. Guest outputs are read only as regular files with a size cap; persistent state lives in the host-only
`meta.json`.
- **vfkit arguments**: paths containing `,` `"` or control characters are refused (vfkit splits options on commas).
Workspaces overlapping `~/.wsbx` are refused.
- **Registry**: references are validated before any request, digest pins are enforced, and every blob/manifest is sha256-verified.
The tag cache is keyed by the exact reference (`a_b:t` and `a/b:t` never share an entry).
Auth realms must be https. For public registries, connections to loopback/private/link-local addresses are refused
(token realms and redirects included, IPv6 forms like NAT64/6to4 too). A registry counts as local only by name:
`localhost` or a private IP literal (`192.168.1.5:5000`). LAN registries addressed by a DNS name are refused; use the IP.
All downloads (registries, kernel) time out after 30 s without progress (connect or any single read).
- **Guest base**: the static busybox (PID 1 in every VM) is pulled pinned by digest. The kernel comes from the Kata release
over the same public-addresses-only client and is sha256-checked against the release's published digest.
- **pi config**: allowlisted items only. Symlinks are followed only into `~/.pi/agent` or `~/.agents/skills`, with no cycles
and no special files, capped at 256 MB.
- **exec**: sessions run as root before dropping to the user, so the guest helper accepts them only from the host's vsock CID,
not from guest processes via vsock loopback.
- **forward**: listens on the host's loopback only. Browsers don't isolate `localhost` cookies by port, so a forwarded guest
page can read non-HttpOnly cookies your other localhost apps set. Forward only what you need.
- **code**: the SSH server is only reachable through `wsbx exec` (your user's `~/.wsbx`), so it skips auth, with an ephemeral host key.
It allows sessions and host → guest forwarding only; guest → host forwarding (`-R`) and agent forwarding are refused. Desktop VS Code
auto-forwards ports the guest opens to your localhost (turn off `remote.autoForwardPorts` if unwanted), and its client
trusts the remote server more than a browser tab does. The browser mode has the same localhost-cookie caveat as `forward`.
- **Host tunnel**: only the ports you pass with `-p` (or the local `baseUrl`s in pi's `models.json`), over vsock.
- **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 run later on the host (`.git/hooks`, `.envrc`,
IDE tasks, package scripts). Review changes before running them on the host.
- Egress is unrestricted NAT. Anything the VM holds (keys passed with `--keys`, API keys in pi's `models.json`, `--pi-auth`)
can be exfiltrated. A host-side credential-injecting egress proxy would fix this; it isn't built yet.
- A kernel panic before the root disk mounts (e.g. a corrupt `disk.img`) still restart-loops; panics after boot stop
the VM (exit 1).
- Image layers are unpacked on the host into one tar, so a decompression bomb can fill the disk.
- 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