From 2dd96316837020711aac3a51e8dd63ed082780af Mon Sep 17 00:00:00 2001 From: Rob Murray Date: Tue, 21 Jul 2026 10:36:10 +0100 Subject: [PATCH] sandboxes: document upstream proxy configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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) Co-Authored-By: Claude Opus 5 (1M context) --- content/manuals/ai/sandboxes/_index.md | 2 + content/manuals/ai/sandboxes/architecture.md | 41 +---- .../ai/sandboxes/security/isolation.md | 4 +- .../manuals/ai/sandboxes/upstream-proxy.md | 170 ++++++++++++++++++ 4 files changed, 184 insertions(+), 33 deletions(-) create mode 100644 content/manuals/ai/sandboxes/upstream-proxy.md diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md index 455fffa2e1b..ba65ce3a7d1 100644 --- a/content/manuals/ai/sandboxes/_index.md +++ b/content/manuals/ai/sandboxes/_index.md @@ -81,6 +81,8 @@ the [usage guide](usage.md) for basic commands. extending or tailoring sandboxes - [Architecture](architecture.md) — microVM isolation, workspace mounting, networking +- [Upstream proxy](upstream-proxy.md) — route sandbox and daemon traffic through + a corporate proxy, PAC file, or your OS system proxy - [Security](security/) — isolation model, credential handling, and network policies - [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options diff --git a/content/manuals/ai/sandboxes/architecture.md b/content/manuals/ai/sandboxes/architecture.md index 5255fcf2f0a..680e3099746 100644 --- a/content/manuals/ai/sandboxes/architecture.md +++ b/content/manuals/ai/sandboxes/architecture.md @@ -69,38 +69,15 @@ upstream proxy, the host-side proxy forwards the request to it. Chaining to an upstream proxy means sandbox traffic respects the same egress controls as other applications on your host. -The sandbox daemon makes these upstream requests, and it reads the proxy -environment variables `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`, along with -their lowercase equivalents. Set `NO_PROXY` to list hosts that should be -reached directly instead of through the upstream proxy. - -To route sandbox traffic through a different proxy, set -`DOCKER_SANDBOXES_PROXY` to the proxy URL. It applies only to sandbox traffic -and sets the upstream proxy for both HTTP and HTTPS to that URL. Unlike -`HTTP_PROXY` and `HTTPS_PROXY`, it doesn't affect image pulls or the daemon's -own requests. - -`DOCKER_SANDBOXES_PROXY` accepts `http://`, `https://`, `socks5://`, and -`socks5h://` URLs. With `socks5://`, DNS is resolved locally before the -connection is handed to the proxy. With `socks5h://`, DNS resolution is -delegated to the proxy. Both schemes support credentials in the URL: -`socks5://user:pass@host:port`. - -Set `DOCKER_SANDBOXES_NO_PROXY` to exclude specific destinations from -`DOCKER_SANDBOXES_PROXY`, using standard comma-separated `NO_PROXY` matching -semantics. This only affects traffic routed through `DOCKER_SANDBOXES_PROXY` -— use `NO_PROXY` to exclude destinations from `HTTP_PROXY`/`HTTPS_PROXY`. - -Set these variables in the environment where the sandbox daemon starts. The -daemon starts automatically the first time a command needs it, so set the -variables before you run a `sbx` command. If the daemon is already running, -run `sbx daemon restart` for a change to take effect. - -One limitation applies: - -- Proxy auto-configuration files, such as `proxy.pac`, aren't supported. Set the - `HTTP_PROXY`, `HTTPS_PROXY`, or `DOCKER_SANDBOXES_PROXY` environment variables - explicitly. +By default, both sandbox traffic and the daemon's own traffic follow your OS +system proxy, so this usually works without any configuration. To set a proxy +explicitly — with a proxy URL, a PAC file, a SOCKS5 proxy, or separate settings +for sandbox and daemon traffic — see +[Configure an upstream proxy](upstream-proxy.md). Upstream proxy support is +experimental and subject to change. + +Only HTTP and HTTPS traffic can be forwarded to an upstream proxy. Other TCP +traffic can't be redirected to a proxy. ## MCP gateway diff --git a/content/manuals/ai/sandboxes/security/isolation.md b/content/manuals/ai/sandboxes/security/isolation.md index ec1469d39d8..917e62bfa85 100644 --- a/content/manuals/ai/sandboxes/security/isolation.md +++ b/content/manuals/ai/sandboxes/security/isolation.md @@ -52,7 +52,9 @@ ranges, loopback, and link-local addresses is also blocked. Only domains explicitly listed in the policy are reachable. For the default set of allowed domains, see -[Default security posture](defaults.md). +[Default security posture](defaults.md). To forward allowed traffic through a +corporate or upstream proxy, see +[Configure an upstream proxy](../upstream-proxy.md). ## Docker Engine isolation diff --git a/content/manuals/ai/sandboxes/upstream-proxy.md b/content/manuals/ai/sandboxes/upstream-proxy.md new file mode 100644 index 00000000000..68b5e1ba064 --- /dev/null +++ b/content/manuals/ai/sandboxes/upstream-proxy.md @@ -0,0 +1,170 @@ +--- +title: Configure an upstream proxy +linkTitle: Upstream proxy +description: Route sandbox and daemon traffic through a corporate or upstream proxy, including PAC files, SOCKS5, and your OS system proxy. +keywords: docker sandboxes, sbx, upstream proxy, corporate proxy, pac, socks5, system proxy, no_proxy, egress, ntlm, kerberos +weight: 75 +--- + +> [!IMPORTANT] +> Upstream proxy support is experimental. Everything described on this page — +> proxy URLs, PAC files, SOCKS5, use of the OS system proxy, proxy +> authentication, and the settings that configure them — is subject to change. +> Share feedback and bug reports in the +> [docker/sbx-releases](https://github.com/docker/sbx-releases) repository. + +An upstream proxy is the corporate or network proxy that Docker Sandboxes +forwards outbound traffic through on its way to the internet. This is separate +from the [network policy](governance/access-controls/network.md), which decides +_which_ destinations are allowed. The upstream proxy decides _how_ allowed +traffic reaches them. + +Docker Sandboxes sends two kinds of outbound traffic, and you can proxy them +independently: + +- Sandbox traffic — network access from inside your sandboxes. +- Daemon traffic — the `sbx` daemon's own access: image pulls, telemetry, + sign-in, and feature flags. + +## Default behavior + +By default, both kinds of traffic use your operating system's proxy settings, +including any PAC URL configured there. You don't need to configure anything. On +macOS and Windows, `sbx` tracks the OS proxy setting while it runs, so a change +to your network, VPN, or PAC configuration is picked up without a restart. If +your OS has no proxy configured, traffic goes direct. + +## Set a proxy manually + +Use `sbx settings set` to override the default for one or both kinds of traffic: + +```console +$ sbx settings set proxy http://proxy.corp:3128 # both kinds of traffic +$ sbx settings set proxy.sandbox socks5://proxy.corp:1080 # sandbox traffic only +$ sbx settings set proxy.daemon direct # daemon traffic only +``` + +A proxy value can be any of the following: + +| Value | Meaning | +| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| _(unset)_ | Fall back to the wider scope, then environment variables, then the OS system proxy (the default) | +| `http://host:port` or `https://host:port` | An HTTP or HTTPS proxy | +| `socks5://host:port` or `socks5h://host:port` | A SOCKS5 proxy | +| `pac+http://host/proxy.pac`, `pac+https://host/proxy.pac`, or `file:///path/proxy.pac` | A PAC (proxy auto-config) file | +| `system` | Force the use of the OS system proxy | +| `direct` | Force a direct connection with no proxy | + +With `socks5://`, DNS is resolved locally before the connection is handed to the +proxy. With `socks5h://`, DNS resolution is delegated to the proxy. + +### Exclude destinations from the proxy + +Exclusion lists mirror the same scopes. Each takes a comma-separated list of +hosts, domain suffixes, IP addresses, or CIDR ranges, or `*` to bypass the +proxy entirely: + +```console +$ sbx settings set no_proxy "*.internal.corp,10.0.0.0/8" # both kinds of traffic +$ sbx settings set no_proxy.sandbox "*.svc.cluster.local" # sandbox traffic only +$ sbx settings set no_proxy.daemon "registry.internal" # daemon traffic only +``` + +## Environment variables + +Because `sbx` runs from your shell, it also honors the standard and legacy proxy +environment variables, so existing setups keep working without migration: + +- `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` (and their lowercase forms) — the + standard variables. They apply to both kinds of traffic when no `proxy` or + `no_proxy` setting is configured. +- `DOCKER_SANDBOXES_PROXY` and `DOCKER_SANDBOXES_NO_PROXY` — the environment + form of `proxy.sandbox` and `no_proxy.sandbox`. They apply to sandbox traffic + only and never affect daemon traffic. + +The daemon reads these variables when it starts, so set them before your first +`sbx` command, or restart the daemon for a change to take effect. + +## Precedence + +For each kind of traffic, the first match wins: + +1. The scope-specific value: + - `proxy.sandbox` or `DOCKER_SANDBOXES_PROXY` for sandbox traffic + - `proxy.daemon` for daemon traffic +2. The `proxy` setting +3. `HTTP_PROXY` or `HTTPS_PROXY` from the shell +4. The OS system proxy (the default) +5. Direct + +The matching exclusion list (`no_proxy.`, then `no_proxy`) applies to the +chosen proxy, and the standard `NO_PROXY` variable still applies on the +environment path. + +For example, if `proxy` specifies a shared proxy and `proxy.sandbox` is set to +`direct`, sandbox traffic connects directly while daemon traffic uses the +shared proxy. If no proxy setting is configured, `HTTP_PROXY` takes precedence +over the OS system proxy. + +## When changes take effect + +The two kinds of traffic are resolved at different times: + +- Sandbox scope (`proxy.sandbox`, `no_proxy.sandbox`, and the sandbox side of + `proxy` and `no_proxy`) is re-resolved every time a sandbox is created or + 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`, and the daemon side of + `proxy` and `no_proxy`) is resolved once when the daemon starts. A change + requires a daemon restart. + +The `DOCKER_SANDBOXES_*` environment variables are a separate case. They control +sandbox traffic only, as described in +[Environment variables](#environment-variables), but `sbx` reads them from the +daemon's environment as the daemon starts, so changing one also requires a +daemon restart. + +When a `system` or PAC proxy is in use, `sbx` still tracks OS-level proxy changes +(such as switching networks, connecting a VPN, or updated PAC contents) live. + +## Authentication + +If the upstream proxy requires you to authenticate to it, `sbx` supports two +mechanisms. + +### Credentials in the proxy URL + +Put the credentials in the proxy URL: `http://user:pass@host:port` for an HTTP +or HTTPS proxy, or `socks5://user:pass@host:port` for SOCKS5. This works on all +platforms and covers proxies that challenge with Basic authentication. + +### Integrated Windows authentication + +Proxies that answer `CONNECT` with a `407` challenge and accept only integrated +schemes — NTLM or Kerberos/Negotiate — can instead authenticate you with your +Windows sign-in identity. This is opt-in and off by default: + +```console +$ sbx settings set proxy.integratedAuth true +``` + +The setting isn't scoped: it applies to both sandbox and daemon traffic. If the +proxy offers several schemes, the strongest one is used, preferring Negotiate +over NTLM. A change takes effect on the same schedule as the other proxy +settings: on the next sandbox you create or restart for sandbox traffic, and +after `sbx daemon restart` for daemon traffic. + +Your identity stays on the host. Authentication to the upstream proxy happens +on the host side of the sandbox boundary, after network policy has already been +applied, so no credential enters the sandbox and nothing about which +destinations a sandbox may reach changes. + +This depends on Windows SSPI, so it has no effect on macOS or Linux. On those +platforms, credentials in the proxy URL remain the only option. + +## Related pages + +- [Network isolation](security/isolation.md) — how traffic leaves a sandbox and + the network policy it passes through +- [Troubleshooting: API calls fail with a certificate error](troubleshooting.md#api-calls-fail-with-a-certificate-error) + — installing an internal root CA when your proxy inspects HTTPS traffic