docs: add gVisor (runsc) integration guide - #6332
Conversation
Explain what gVisor is (application kernel, Sentry, netstack, Systrap/KVM platforms) and how AWF runs the agent under the runsc OCI runtime: the compose executionModel, runtime field wiring, the netstack DNS workaround (extra_hosts + chroot /host/etc/hosts patching), iptables DNAT compat, and the Bun JIT shim. Includes guidance for adding other compose-model runtimes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 23717692-af7a-4e03-a156-5b696c3f01bd
|
@copilot fix this failing ci check https://github.com/github/gh-aw-firewall/actions/runs/29604416738/job/87964101538?pr=6332 |
There was a problem hiding this comment.
Pull request overview
Adds a detailed guide explaining gVisor’s architecture, AWF integration, and considerations for additional OCI runtimes.
Changes:
- Documents gVisor isolation platforms and limitations.
- Explains AWF runtime, DNS, networking, and compatibility handling.
- Provides guidance for adding compose-model runtimes.
Show a summary per file
| File | Description |
|---|---|
docs/gvisor-integration.md |
Adds the gVisor integration guide. |
Review details
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 5
- Review effort level: Medium
|
|
||
| :::note | ||
| gVisor is the **compose-model** counterpart to the microVM backend documented in | ||
| [Docker Sandboxes (sbx) integration](./sbx-integration.md). With gVisor the agent |
| - AWF source: `src/container-runtime.ts`, `src/services/agent-service.ts`, | ||
| `src/topology.ts`, `src/services/agent-environment/tool-specific-environment.ts` | ||
| - CI: `.github/workflows/test-gvisor-compat.yml`, `.github/workflows/smoke-gvisor*.md` | ||
| - Related: [Docker Sandboxes (sbx) integration](./sbx-integration.md), |
| fallback to hold. This is verified by | ||
| `.github/workflows/test-gvisor-compat.yml`, which confirms iptables DNAT and | ||
| proxy reachability inside a `runsc` sandbox. |
| - **Bun JIT crash on Claude** (`tool-specific-environment.ts`) — when the agent | ||
| is Claude *and* the runtime is gVisor, AWF sets `BUN_JSC_useJIT=0` to force | ||
| Bun's interpreter, avoiding a JIT crash under gVisor | ||
| ([oven-sh/bun#22901](https://github.com/oven-sh/bun/issues/22901)). |
| That single entry makes `resolveDockerRuntime` set the compose `runtime:` field | ||
| and (optionally) turns on the static-DNS workaround — no other code changes are | ||
| required for the common case, because the agent remains a compose service. |
Fixed in 0490a63. The failing Link Check job was caused by two relative links to |
|
@copilot address the review feedback |
Addressed in 9806cfb. I updated the guide to describe |
|
✅ Copilot review passed with no inline comments. @lpcox Add the |
What
Adds
docs/gvisor-integration.md, a deep-dive on gVisor and how AWF runs the agent under therunscOCI runtime via--container-runtime gvisor.Why
Companion to the Docker Sandboxes (sbx) integration doc (PR #6331). Two audiences:
Contents
composeexecutionModelincontainer-runtime.ts(agent stays a compose service, unlike sbx);agent-service.tssettingruntime: runsc; the netstack DNS problem (127.0.0.11unreachable, Netfilter config is not handled on runsc boot, reopen of: "DNS not working in Docker Compose" google/gvisor#7469) and AWF's two-part workaround (IP-based proxy env vars + staticextra_hostsand the chrooted/host/etc/hostspatch intopology.ts); the iptables-DNAT compat requirement verified bytest-gvisor-compat.yml; and the Bun-JIT shim for Claude.Notes
markdownlint-cli2passes on the new file; cross-links use the relative./file.mdstyle consistent with the rest ofdocs/.