docker · robmry · Jul 21, 2026
@@ -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

@@ -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
 

@@ -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
 

@@ -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.<scope>`, 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