sandboxes: document upstream proxy configuration - #25610
Conversation
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
689c1a9 to
f80057d
Compare
2611092 to
2f116ef
Compare
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟢 APPROVE
The new upstream-proxy.md page and supporting edits to _index.md, architecture.md, and security/isolation.md are well-structured and follow Docker documentation standards.
Checked:
- ✅ No vendored/generated files edited
- ✅ No pages removed or moved — no redirect concerns
- ✅ Front matter complete (
title,description,keywords,weight,linkTitle) - ✅ No AI hedge words (
simply,easily,just,seamlessly) - ✅ No
allows you to/enables you toviolations - ✅ No bold misuse (only UI elements bolded)
- ✅ No time-relative language (
currently,new,recently) - ✅ All relative links resolve to existing files (
governance/access-controls/network.md,security/isolation.md,troubleshooting.md) - ✅ Hugo shortcode syntax correct
- ✅ Scope preserved in edited files (
architecture.mdtrimmed appropriately)
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
| restarted. A change takes effect on the next sandbox you create or restart; | ||
| already-running sandboxes keep the proxy they were created with. | ||
| - Daemon scope (`proxy.daemon`, `no_proxy.daemon`, the daemon side of `proxy` and | ||
| `no_proxy`, and the `DOCKER_SANDBOXES_*` environment variables) is resolved |
There was a problem hiding this comment.
[MEDIUM] DOCKER_SANDBOXES_* variables described as sandbox-scope traffic but grouped in the Daemon scope timing bucket without reconciling explanation
The "Environment variables" section (line 81–83) explicitly states that DOCKER_SANDBOXES_PROXY and DOCKER_SANDBOXES_NO_PROXY "apply to sandbox traffic only and never affect daemon traffic." However, the "When changes take effect" section groups them under the Daemon scope bullet, listing them alongside proxy.daemon and no_proxy.daemon.
A reader who reaches the timing section without carrying the earlier context forward may infer from the section heading that these variables affect daemon traffic — directly contradicting the earlier statement. The timing section uses "Daemon scope" to mean "when the daemon resolves the value (at startup)," but readers can reasonably interpret it as "what traffic this controls."
Consider adding a parenthetical to clarify the grouping, for example:
- Daemon scope (`proxy.daemon`, `no_proxy.daemon`, the daemon side of `proxy` and
`no_proxy`, and the `DOCKER_SANDBOXES_*` environment variables — which affect sandbox
traffic only but are read by the daemon at startup) is resolved once when the daemon
starts. A change requires a daemon restart.Or restructure the bullet to separate timing from scope:
- The `DOCKER_SANDBOXES_*` environment variables affect sandbox traffic only (see
[Environment variables](#environment-variables)) but are read by the daemon at startup,
so a change also requires a daemon restart.There was a problem hiding this comment.
I think a bullet separating timing from scope makes sense ☝️
There was a problem hiding this comment.
Great — I'll draft a separate bullet to make that distinction clearer. The new structure will keep the timing information ("read at daemon startup, requires daemon restart") while explicitly referencing back to the earlier section that defines what traffic the variables control.
This should prevent readers from conflating "when the daemon resolves these values" with "what kind of traffic they affect."
There was a problem hiding this comment.
Great — I'll draft a separate bullet to make that distinction clearer.
O rly?
There was a problem hiding this comment.
Good catch, and both statements were true — it was the grouping that misled. Checked against the implementation before changing anything: sandbox-scope proxy config is resolved inside the daemon (backend_dockernext.go → platform.ResolveUpstreamProxy), so DOCKER_SANDBOXES_* really does control sandbox traffic only, while its value comes from the daemon's environment and is therefore fixed at daemon start.
Taken out of the daemon-scope bullet and given its own paragraph, so scope and timing are stated separately:
The
DOCKER_SANDBOXES_*environment variables are a separate case. They control
sandbox traffic only, as described in
Environment variables, butsbxreads them from the
daemon's environment as the daemon starts, so changing one also requires a
daemon restart.
Written by Claude Code on behalf of @robmry.
dvdksn
left a comment
dvdksn
left a comment
There was a problem hiding this comment.
Looks good! just two nonblocking suggestions
Add a page covering the settings-driven, per-scope upstream proxy: proxy URLs, PAC files, SOCKS5, the OS system proxy, and separate sandbox/daemon scopes, plus precedence, the environment-variable bindings, and upstream proxy authentication — credentials in the proxy URL on all platforms, and opt-in integrated NTLM/Kerberos via proxy.integratedAuth on Windows. Mark upstream proxy support as experimental. That covers the whole feature — proxy URLs, PAC files, SOCKS5, the OS system proxy, and authentication — not only the settings that configure it. Trim the architecture page's upstream proxy section to the concept plus the HTTP/HTTPS-only limitation, and link to the new page for configuration. Cross-link from the section index and the network isolation page. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
2f116ef to
2dd9631
Compare
3 participants
Description
Documents the settings-driven, per-scope upstream proxy configuration for Docker Sandboxes, covering the user-facing surface of these
docker/sandboxesPRs:system(OS proxy) support(#3977 is a pure internal refactor with no user-facing surface.)
Changes
content/manuals/ai/sandboxes/upstream-proxy.md— "Configure an upstream proxy": default behavior (OS system proxy),sbx settings set proxy[.sandbox|.daemon], the value table (URL / PAC / SOCKS5 /system/direct), exclusion lists, environment-variable bindings, precedence, when changes take effect, and proxy authentication.proxy.integratedAuthsetting for integrated NTLM and Kerberos/Negotiate on Windows — including that it isn't scoped, when a change takes effect, and that the host identity never enters the sandbox.[!IMPORTANT]callout on the new page, plus a one-line marker in thearchitecture.mdsection that links to it.architecture.md— trimmed the upstream proxy section to the architectural concept plus the HTTP/HTTPS-only limitation, and pointed to the new page for configuration (so env vars are no longer framed as the way to configure it)._index.md) and the network isolation page.Rebase
All the upstream PRs above are now merged, so the earlier "draft until #4413 lands" caveat no longer applies. The branch has been rebased onto
main, which had meanwhile:weight: 50(which now collides with the MCP gateway page) toweight: 75, placing it after Architecture;governance/access-controls/network.md;architecture.mdparagraphs that this PR replaces (the only rebase conflict; resolved in favour of the replacement text).🤖 Generated with Claude Code
Written by Claude Code on behalf of @robmry.