Share feedback
Answers are generated based on the documentation.

Configure an upstream proxy

Table of contents
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 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, 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:

$ 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:

ValueMeaning
(unset)Fall back to the wider scope, then environment variables, then the OS system proxy (the default)
http://host:port or https://host:portAn HTTP or HTTPS proxy
socks5://host:port or socks5h://host:portA SOCKS5 proxy
pac+http://host/proxy.pac, pac+https://host/proxy.pac, or file:///path/proxy.pacA PAC (proxy auto-config) file
systemForce the use of the OS system proxy
directForce 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:

$ 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, 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:

$ 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.