93 lines
7.3 KiB
Markdown
93 lines
7.3 KiB
Markdown
# 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.
|
|
|
|
```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
|
|
```
|
|
|
|
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.
|
|
|
|
Options: `--name --workspace --cpus --memory --disk --env K[=V] --host-port/-p PORT --fresh --pull --kernel`.
|
|
|
|
**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.
|
|
|
|
**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.
|
|
|
|
**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).
|
|
|
|
**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.
|
|
|
|
**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.
|
|
|
|
[vfkit]: https://github.com/crc-org/vfkit
|
|
|
|
## Security model
|
|
|
|
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.
|
|
Auth realms must be https. For public registries, connections to loopback/private/link-local addresses are refused
|
|
(token realms and redirects included).
|
|
- **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.
|
|
|
|
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.
|