docs: add Docker Sandboxes (sbx) integration guide - #6331
Merged
Merged
Conversation
Explain what Docker Sandboxes (sbx) is and how AWF uses it as a microVM backend: the executionModel abstraction, sbx-manager lifecycle wrapper, main-action wiring, egress chaining through AWF's Squid, credential injection via the api-proxy, and secret sanitization. Includes a guide for adding another KVM-based microVM backend. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 23717692-af7a-4e03-a156-5b696c3f01bd
Contributor
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a guide for AWF’s optional Docker Sandboxes microVM backend and future backend development.
Changes:
- Documents sbx architecture and AWF lifecycle integration.
- Describes networking, credential isolation, and traffic flow.
- Provides a checklist for adding KVM-based backends.
Show a summary per file
| File | Description |
|---|---|
docs/sbx-integration.md |
Adds the sbx integration and extension 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: 8
- Review effort level: Medium
Comment on lines
+175
to
+179
| - **Squid** is reached at the **sbx gateway IP** (`172.17.0.0` in code, i.e. the | ||
| docker0 bridge range) on its published port `3128`, rather than the internal | ||
| `172.30.0.10`. AWF sets `DOCKER_SANDBOXES_PROXY = http://<squidIp>:3128` so the | ||
| sandbox's own proxy chains upstream into AWF's Squid, where the domain ACL is | ||
| enforced. |
Contributor
There was a problem hiding this comment.
Fixed in docs: correct DOCKER_SANDBOXES_PROXY claim in sbx-integration.md. The networking section now accurately documents that:
- AWF sets
HTTP_PROXY/HTTPS_PROXYinside the sandbox (notDOCKER_SANDBOXES_PROXY) DOCKER_SANDBOXES_PROXYis explicitly noted as not set by AWF, with the reason (it's a daemon-start setting AWF doesn't control)- The "net effect" clarifies only proxy-aware tools are covered by AWF's Squid ACL
The mermaid diagram was also updated to show the actual traffic flow: proxy-aware tools → Squid; proxy-unaware tools → sbxproxy (not filtered by AWF ACL).
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Contributor
|
✅ Copilot review passed with no inline comments. @lpcox Add the |
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.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.
What
Adds
docs/sbx-integration.md, a deep-dive on Docker Sandboxes (sbx) and how AWF uses it as an optional microVM backend for agent isolation.Why
Two audiences:
--container-runtime sbxpath works.Contents
sbxis — Docker's microVM product: per-sandbox kernel + Docker Engine (KVM on Linux), virtiofs workspace passthrough, host-side proxy for deny-by-default egress and credential injection, and theDOCKER_SANDBOXES_PROXYupstream-proxy hook. Sourced from the official Docker Sandboxes docs.executionModel(composevsmicrovm) registry insrc/container-runtime.ts; thesbx-manager.tslifecycle wrapper;main-action.tswiring (sbxStartContainers/sbxRunAgentCommand); egress chaining through AWF's Squid (gateway IP + published 3128); credential injection via the api-proxy overhost.docker.internal; secret sanitization; and the strict-security handling for microVM runtimes.main-action.tswiring, and lessons learned (daemon/proxy ordering, cross-boundary health gating, env-leakage separation, DNS, exit-code fidelity).Notes
markdownlint-cli2passes on the new file; cross-links use the relative./file.mdstyle consistent with the rest ofdocs/.docs/sandbox-design.md(which explains why the default backend is Docker + Squid rather than a microVM).