[quickbeard]

Stacked on #226 (the stdin boot-script delivery this feature's fail-closed script depends on).

Why not "per-distro Hyper-V firewall rules"

The planned mechanism cannot deliver the intent, verified live on Windows 11 / WSL 2.7.11:

• Hyper-V firewall rules target a VMCreatorId — all of WSL at once. There is no per-distribution targeting (cmdlet surface + Microsoft docs).
• Every WSL2 distro shares one utility VM, one network namespace, one IP: Ubuntu and docker-desktop on the test machine report the same /proc/self/ns/net inode and the same eth0 address. A creator-wide DefaultOutboundAction Block would cut off the user's own distros and Docker Desktop.

The only enforcement point that can tell this sandbox's traffic from its neighbours' is the shared guest kernel.

Design

The root boot script, before dropping privileges: mounts cgroup v1 net_cls, gives the sandbox's group a classid derived from its host-reserved server port (unique per running sandbox), moves itself in (server, socat and every agent tool inherit), and installs an nftables table:

• meta cgroup <classid> oifname "lo" accept — the sandbox's own server and the broker stub
• meta cgroup <classid> ip daddr $HOST_IP tcp dport <brokerPort> accept — only when a broker is configured
• meta cgroup <classid> reject — everything else fails immediately, matching the NIC-less backends

meta cgroup (classid) rather than socket cgroupv2: Microsoft's kernel ships # CONFIG_NFT_SOCKET is not set — the cgroup2 match fails to load (observed: Could not process rule: No such file or directory), while CONFIG_CGROUP_NET_CLASSID=y. Fail closed: every step aborts the boot on failure, no elevation needed (all guest-side root).

The guest image gains the nftables package (~1 MB with libs). Rollout: a sandbox on an older image fails to start with "nft is missing from the guest image" until Reset — the image must be published before/with the app release.

Verification (live, Windows 11 / WSL 2.7.11 / kernel 6.18.33.2)

bun script/e2e-wsl.ts --image dist-images\bwrap-x64.tar.gz --bundle ..\opencode\dist\node --egress with a locally built image:

health: OK
path api: OK
broker via cgroup: OK
direct egress inside cgroup: blocked OK (BLOCKED:ECONNREFUSED)
direct egress outside cgroup: OK
firewall: OK
e2e OK

Plus 24 unit tests in packages/codev-sandbox (bun test src/wsl/), typecheck clean.

Residual exposure (documented in firewall.ts)

• The VM loopback is shared by all distros; the blanket lo allow means a sandbox can reach neighbour distros' 127.0.0.1 services. Not closable by port rules without breaking the agent's own localhost dev-server workflows.
• Found while verifying, pre-existing and out of scope here: two concurrent WSL sandboxes collide on the guest-loopback broker stub port 8788 (shared VM loopback) — the second sandbox's socat loses the bind and its model traffic hits the first sandbox's broker, which 401s it. Needs a per-sandbox stub address; filed in the session report.

🤖 Generated with Claude Code