Files
woiken-sandboxes/README.md
T
niklas cff6dae88f Add image gc, stop VMs on kernel panic, harden first boot
- Add `wsbx gc` to delete cached images that no sandbox uses, and
  drop the superseded image automatically when a tag moves to a new
  digest (unless another ref still points at it).
- Boot the guest with panic=1. Virtualization.framework restarts a
  rebooting guest, so init now leaves a marker in the per-launch
  control share and powers off when it is already there. A kernel
  panic (or a reboot inside the VM) now ends the run with exit 1
  instead of hanging or looping forever.
- Report a VM that stops without an exit status as an error.
- Sync the first-boot image unpack before marking the sandbox
  provisioned; a crash right after first boot previously left an
  empty root filesystem.
- Validate kernel, workspace and state-dir paths before creating any
  sandbox files, so rejected runs no longer leave a sandbox behind.
- Ignore .llm-wiki/, commit .gitignore, fix the remaining Clippy
  warning, and document gc and the panic behavior.
2026-10-02 15:33:30 +02:00

63 lines
4.2 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 .
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 ls / wsbx rm NAME / 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`.
**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.
- **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.