diff --git a/README.md b/README.md
index 2bb638e..5a6379b 100644
--- a/README.md
+++ b/README.md
@@ -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
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
+```
-**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
diff --git a/install.sh b/install.sh
new file mode 100755
index 0000000..9769da3
--- /dev/null
+++ b/install.sh
@@ -0,0 +1,29 @@
+#!/bin/sh
+# Install wsbx from a release: curl -fsSL https://git.nhaiden.io/niklas/woiken-sandboxes/raw/branch/main/install.sh | sh
+# Env: WSBX_VERSION (tag, default: latest release), WSBX_INSTALL_DIR (default: ~/.local/bin)
+set -eu
+
+REPO=https://git.nhaiden.io/niklas/woiken-sandboxes
+DIR=${WSBX_INSTALL_DIR:-$HOME/.local/bin}
+
+[ "$(uname -s)-$(uname -m)" = Darwin-arm64 ] || { echo "wsbx needs macOS on Apple Silicon" >&2; exit 1; }
+
+TAG=${WSBX_VERSION:-$(curl -fsSL https://git.nhaiden.io/api/v1/repos/niklas/woiken-sandboxes/releases/latest | sed -n 's/.*"tag_name":"\([^"]*\)".*/\1/p')}
+[ -n "$TAG" ] || { echo "could not determine the latest release" >&2; exit 1; }
+F="wsbx-$TAG-darwin-arm64.tar.gz"
+
+TMP=$(mktemp -d)
+trap 'rm -rf "$TMP"' EXIT
+cd "$TMP"
+echo "downloading $F"
+curl -fsSLO "$REPO/releases/download/$TAG/$F"
+curl -fsSLO "$REPO/releases/download/$TAG/$F.sha256"
+shasum -a 256 -c "$F.sha256" >/dev/null || { echo "checksum mismatch for $F" >&2; exit 1; }
+tar -xzf "$F" wsbx
+
+mkdir -p "$DIR"
+install -m 755 wsbx "$DIR/wsbx"
+echo "installed $("$DIR/wsbx" --version) to $DIR/wsbx"
+
+case ":$PATH:" in *":$DIR:"*) ;; *) echo "note: $DIR is not on your PATH" ;; esac
+command -v vfkit >/dev/null || echo "note: wsbx needs vfkit and e2fsprogs: brew install vfkit e2fsprogs"