Repository navigation
feat(sandbox): add the bubblewrap provider (sandbox Phase 1) - #197
Merged
Merged
Conversation
First platform backend for the sandbox: an Ubuntu provider that runs the codev server inside bubblewrap with unshared user/pid/net/uts/ipc namespaces — loopback-only networking, read-only rootfs binds (merged-usr symlinks preserved), project rw at /workspace, server bundle ro at /opt/codev, per-sandbox home, cleared env. - bwrap/args.ts: pure bwrap invocation builder - bwrap/bridge.ts: unix-socket bridges that cross the guest netns — a host-side TCP-to-unix forwarder plus the guest-side node forward script for the server and broker paths - bwrap/rootfs.ts: tar unpack + rootfs layout probing - bwrap/provider.ts: SandboxProvider with an availability probe that detects the Ubuntu 23.10+ AppArmor userns restriction, health-gated start with stderr capture, and create/reset/destroy dir management - boot.ts: checkSandboxHealth (basic-auth /global/health probe) - broker.ts: listenUnix so the broker can serve netns-isolated guests - turbo.json: register @codev/sandbox#test so CI's `bun turbo test` gates the package (DIVERGENCES.md row added) Real-bwrap integration tests auto-skip where bwrap can't run (macOS, AppArmor-restricted runners). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Phase 1 of the desktop sandbox: the first platform backend, an Ubuntu bubblewrap provider implementing the
SandboxProvidercontract from Phase 0 (#196). The codev server runs inside bwrap with unshared user/pid/net/uts/ipc namespaces — the guest's only network interface is loopback, and its only paths out are unix sockets bind-mounted at/run/codev, per the agreed NIC-less + host-broker design.How it works
bwrap/args.ts— pure invocation builder: read-only rootfs binds with merged-usr symlinks preserved (/bin -> usr/binrecreated as--symlink), project rw at/workspace, server bundle ro at/opt/codev(injected from the host for automatic version parity), per-sandbox home,--clearenv+ the boot env contract,--die-with-parent.bwrap/bridge.ts— how TCP crosses the network namespace: unix sockets are filesystem objects, so a host-side TCP→unix forwarder gives the renderer its usualhttp://127.0.0.1:<port>+ Basic-auth contract, and a guest-side node forward script (run with the image's node) bridges unix↔TCP inside — one script serves both the server path (unix-to-tcp) and the broker path (tcp-to-unix).bwrap/rootfs.ts— tar unpack into per-sandbox dirs + top-level layout probing.bwrap/provider.ts— availability probe (bwrap --ro-bind / / true) that distinguishes "not installed" from "cannot create sandboxes" (the Ubuntu 23.10+ AppArmor userns restriction, with guidance in the message);createstages the manifest image (SHA-256-verified, content-addressed) and unpacks it;startis health-gated (/global/healthwith generated credentials) with a 30s timeout, stderr-tail capture in errors, and clean kill on failure;resetwipes rootfs + home and re-unpacks from the cached image without re-downloading.broker.ts— gainslistenUnixso the egress broker can serve netns-isolated guests;boot.tsgainscheckSandboxHealth.CI
turbo.jsonnow registers@codev/sandbox#test, sobun turbo test(the unit CI job) runs this package — previously it was silently skipped. That's an upstream-file edit: DIVERGENCES.md row added in this PR.The real-bwrap integration tests (
bwrap.integration.test.ts) verify loopback-only networking via/proc/net/dev, workspace rw vs rootfs ro, and env clearing against actual bubblewrap, using the host's own/usras rootfs so no image download is needed. They auto-skip where bwrap can't run (macOS, AppArmor-restricted runners) via a capability probe rather than a platform check.Notes
Testing
bun testinpackages/codev-sandbox: 51 pass / 2 skipped (the real-bwrap integration tests, correctly skipped on this macOS machine), 138 assertions — including end-to-end bridge chains (host TCP → forwarder → unix socket → guest script → guest TCP, both directions) and full create/reset/destroy against a staged image over real HTTP.bun typecheckinpackages/codev-sandbox: clean.bun turbo test --filter=@codev/sandboxfrom root: runs and passes, confirming the CI registration.🤖 Generated with Claude Code