Skip to content

Commit f80057d

Browse files
robmryclaude
robmry
and
claude
committed
sandboxes: document upstream proxy configuration
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 and the environment-variable bindings. 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>
1 parent 04ce462 commit f80057d

4 files changed

Lines changed: 139 additions & 33 deletions

File tree

‎content/manuals/ai/sandboxes/_index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,8 @@ the [usage guide](usage.md) for basic commands.
7777
extending or tailoring sandboxes
7878
- [Architecture](architecture.md) — microVM isolation, workspace mounting,
7979
networking
80+
- [Upstream proxy](upstream-proxy.md) — route sandbox and daemon traffic through
81+
a corporate proxy, PAC file, or your OS system proxy
8082
- [Security](security/) — isolation model, credential handling, and
8183
network policies
8284
- [CLI reference](/reference/cli/sbx/) — full list of `sbx` commands and options

‎content/manuals/ai/sandboxes/architecture.md‎

Lines changed: 8 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -67,38 +67,14 @@ upstream proxy, the host-side proxy forwards the request to it. Chaining to an
6767
upstream proxy means sandbox traffic respects the same egress controls as other
6868
applications on your host.
6969

70-
The sandbox daemon makes these upstream requests, and it reads the proxy
71-
environment variables `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY`, along with
72-
their lowercase equivalents. Set `NO_PROXY` to list hosts that should be
73-
reached directly instead of through the upstream proxy.
74-
75-
To route sandbox traffic through a different proxy, set
76-
`DOCKER_SANDBOXES_PROXY` to the proxy URL. It applies only to sandbox traffic
77-
and sets the upstream proxy for both HTTP and HTTPS to that URL. Unlike
78-
`HTTP_PROXY` and `HTTPS_PROXY`, it doesn't affect image pulls or the daemon's
79-
own requests.
80-
81-
`DOCKER_SANDBOXES_PROXY` accepts `http://`, `https://`, `socks5://`, and
82-
`socks5h://` URLs. With `socks5://`, DNS is resolved locally before the
83-
connection is handed to the proxy. With `socks5h://`, DNS resolution is
84-
delegated to the proxy. Both schemes support credentials in the URL:
85-
`socks5://user:pass@host:port`.
86-
87-
Set `DOCKER_SANDBOXES_NO_PROXY` to exclude specific destinations from
88-
`DOCKER_SANDBOXES_PROXY`, using standard comma-separated `NO_PROXY` matching
89-
semantics. This only affects traffic routed through `DOCKER_SANDBOXES_PROXY`
90-
— use `NO_PROXY` to exclude destinations from `HTTP_PROXY`/`HTTPS_PROXY`.
91-
92-
Set these variables in the environment where the sandbox daemon starts. The
93-
daemon starts automatically the first time a command needs it, so set the
94-
variables before you run a `sbx` command. If the daemon is already running,
95-
restart it for a change to take effect.
96-
97-
One limitation applies:
98-
99-
- Proxy auto-configuration files, such as `proxy.pac`, aren't supported. Set the
100-
`HTTP_PROXY`, `HTTPS_PROXY`, or `DOCKER_SANDBOXES_PROXY` environment variables
101-
explicitly.
70+
By default, both sandbox traffic and the daemon's own traffic follow your OS
71+
system proxy, so this usually works without any configuration. To set a proxy
72+
explicitly — with a proxy URL, a PAC file, a SOCKS5 proxy, or separate settings
73+
for sandbox and daemon traffic — see
74+
[Configure an upstream proxy](upstream-proxy.md).
75+
76+
Only HTTP and HTTPS traffic can be forwarded to an upstream proxy. Other TCP
77+
traffic can't be redirected to a proxy.
10278

10379
## Lifecycle
10480

‎content/manuals/ai/sandboxes/security/isolation.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,9 @@ ranges, loopback, and link-local addresses is also blocked. Only domains
5050
explicitly listed in the policy are reachable.
5151

5252
For the default set of allowed domains, see
53-
[Default security posture](defaults.md).
53+
[Default security posture](defaults.md). To forward allowed traffic through a
54+
corporate or upstream proxy, see
55+
[Configure an upstream proxy](../upstream-proxy.md).
5456

5557
## Docker Engine isolation
5658

‎content/manuals/ai/sandboxes/upstream-proxy.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: Configure an upstream proxy
3+
linkTitle: Upstream proxy
4+
description: Route sandbox and daemon traffic through a corporate or upstream proxy, including PAC files, SOCKS5, and your OS system proxy.
5+
keywords: docker sandboxes, sbx, upstream proxy, corporate proxy, pac, socks5, system proxy, no_proxy, egress
6+
weight: 50
7+
---
8+
9+
An upstream proxy is the corporate or network proxy that Docker Sandboxes
10+
forwards outbound traffic through on its way to the internet. This is separate
11+
from the [network policy](governance/), which decides _which_ destinations are
12+
allowed. The upstream proxy decides _how_ allowed traffic reaches them.
13+
14+
Docker Sandboxes sends two kinds of outbound traffic, and you can proxy them
15+
independently:
16+
17+
- Sandbox traffic — network access from inside your sandboxes.
18+
- Daemon traffic — the `sbx` daemon's own access: image pulls, telemetry,
19+
sign-in, and feature flags.
20+
21+
## Default behavior
22+
23+
By default, both kinds of traffic use your operating system's proxy settings,
24+
including any PAC URL configured there. You don't need to configure anything. On
25+
macOS and Windows, `sbx` tracks the OS proxy setting while it runs, so a change
26+
to your network, VPN, or PAC configuration is picked up without a restart. If
27+
your OS has no proxy configured, traffic goes direct.
28+
29+
## Set a proxy manually
30+
31+
Use `sbx settings set` to override the default for one or both kinds of traffic:
32+
33+
```console
34+
$ sbx settings set proxy http://proxy.corp:3128 # both kinds of traffic
35+
$ sbx settings set proxy.sandbox socks5://proxy.corp:1080 # sandbox traffic only
36+
$ sbx settings set proxy.daemon direct # daemon traffic only
37+
```
38+
39+
A proxy value can be any of the following:
40+
41+
| Value | Meaning |
42+
| -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
43+
| _(unset)_ | Fall back to the wider scope, then environment variables, then the OS system proxy (the default) |
44+
| `http://host:port` or `https://host:port` | An HTTP or HTTPS proxy |
45+
| `socks5://host:port` or `socks5h://host:port` | A SOCKS5 proxy |
46+
| `pac+http://host/proxy.pac`, `pac+https://host/proxy.pac`, or `file:///path/proxy.pac` | A PAC (proxy auto-config) file |
47+
| `system` | Force the use of the OS system proxy |
48+
| `direct` | Force a direct connection with no proxy |
49+
50+
With `socks5://`, DNS is resolved locally before the connection is handed to the
51+
proxy. With `socks5h://`, DNS resolution is delegated to the proxy.
52+
53+
### Exclude destinations from the proxy
54+
55+
Exclusion lists mirror the same scopes. Each takes a comma-separated list of
56+
hosts, domain suffixes, IP addresses, or CIDR ranges, or `*` to bypass the
57+
proxy entirely:
58+
59+
```console
60+
$ sbx settings set no_proxy "*.internal.corp,10.0.0.0/8" # both kinds of traffic
61+
$ sbx settings set no_proxy.sandbox "*.svc.cluster.local" # sandbox traffic only
62+
$ sbx settings set no_proxy.daemon "registry.internal" # daemon traffic only
63+
```
64+
65+
## Environment variables
66+
67+
Because `sbx` runs from your shell, it also honors the standard and legacy proxy
68+
environment variables, so existing setups keep working without migration:
69+
70+
- `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` (and their lowercase forms) — the
71+
standard variables. They apply to both kinds of traffic when no `proxy` or
72+
`no_proxy` setting is configured.
73+
- `DOCKER_SANDBOXES_PROXY` and `DOCKER_SANDBOXES_NO_PROXY` — the environment
74+
form of `proxy.sandbox` and `no_proxy.sandbox`. They apply to sandbox traffic
75+
only and never affect daemon traffic.
76+
77+
The daemon reads these variables when it starts, so set them before your first
78+
`sbx` command, or restart the daemon for a change to take effect.
79+
80+
## Precedence
81+
82+
For each kind of traffic, the first match wins:
83+
84+
1. The scope-specific setting (`proxy.sandbox` or `proxy.daemon`; sandbox traffic
85+
can also use the `DOCKER_SANDBOXES_PROXY` environment variable)
86+
2. The `proxy` setting
87+
3. `HTTP_PROXY` or `HTTPS_PROXY` from the shell
88+
4. The OS system proxy (the default)
89+
5. Direct
90+
91+
The matching exclusion list (`no_proxy.<scope>`, then `no_proxy`) applies to the
92+
chosen proxy, and the standard `NO_PROXY` variable still applies on the
93+
environment path.
94+
95+
> [!NOTE]
96+
> The most specific value you set wins. Set nothing, and traffic uses the OS
97+
> system proxy. A shell `HTTP_PROXY` counts as being set and takes precedence
98+
> over the OS setting, the same way `curl` behaves.
99+
100+
## When changes take effect
101+
102+
The two kinds of traffic are resolved at different times:
103+
104+
- Sandbox scope (`proxy.sandbox`, `no_proxy.sandbox`, and the sandbox side of
105+
`proxy` and `no_proxy`) is re-resolved every time a sandbox is created or
106+
restarted. A change takes effect on the next sandbox you create or restart;
107+
already-running sandboxes keep the proxy they were created with.
108+
- Daemon scope (`proxy.daemon`, `no_proxy.daemon`, the daemon side of `proxy` and
109+
`no_proxy`, and the `DOCKER_SANDBOXES_*` environment variables) is resolved
110+
once when the daemon starts. A change requires a daemon restart.
111+
112+
When a `system` or PAC proxy is in use, `sbx` still tracks OS-level proxy changes
113+
(such as switching networks, connecting a VPN, or updated PAC contents) live.
114+
115+
## Authentication
116+
117+
Authenticating to the upstream proxy itself is supported only through explicit
118+
credentials in the proxy URL, for example `http://user:pass@host:port`.
119+
Integrated NTLM, Kerberos, and system single sign-on aren't yet supported.
120+
121+
## Related pages
122+
123+
- [Network isolation](security/isolation.md) — how traffic leaves a sandbox and
124+
the network policy it passes through
125+
- [Troubleshooting: API calls fail with a certificate error](troubleshooting.md#api-calls-fail-with-a-certificate-error)
126+
— installing an internal root CA when your proxy inspects HTTPS traffic

0 commit comments

Comments
 (0)