docs: document cloud connections through upstream proxies

Proxy guidance excluded host connections to cloud sandboxes. Document their proxy scope and the direct cloud SSH setting, and link the cloud SSH workflow to that guidance.
This commit is contained in:
David Karlsson committed 2026-10-21 11:09:42 +00:00
1 parent 114c744d24
commit 63b70a9b36
3 files changed
+39 -12

No files matched your search

@@ -131,6 +131,9 @@ $ ssh sbx_01abc123@sbx_cloud
Replace the example with `ssh <sandbox-id>@sbx_cloud`, using the
`sbx_`-prefixed ID from `sbx --cloud ls`.
Cloud SSH honors your host's configured upstream proxy. If the proxy refuses
SSH connections, see [Cloud SSH proxy configuration](../configuration/upstream-proxy.md#cloud-ssh).
## Transfer files
Use `sbx --cloud cp` to copy files or directories between the client machine
@@ -534,8 +534,8 @@ updated value; existing sandbox proxies require a daemon restart.
{{< setting-metadata type="string" default="Empty string" >}}
Use this to route the daemon's requests, such as image pulls, separately from
sandbox traffic. Supported host CLI requests, including `sbx login` and
`sbx diagnose --upload`, also use this scope.
sandbox traffic. Host CLI connections, including connections to cloud sandboxes,
also use this scope. See [traffic scopes](upstream-proxy.md).
For example, keep a shared proxy for sandbox traffic while letting the daemon
connect directly:
@@ -548,6 +548,15 @@ $ sbx daemon restart
Unset this setting to inherit `proxy`. Supported CLI requests use changes on
the next invocation; the daemon's own requests require a restart.
#### proxy.sshDirect {.wrap-anywhere}
{{< setting-metadata type="boolean" default="false" >}}
Set this to `true` to bypass the upstream proxy for cloud SSH connections.
Other host CLI requests keep using the configured proxy. Changes apply on the
next SSH connection without a daemon restart. For setup, see
[Cloud SSH](upstream-proxy.md#cloud-ssh).
#### no_proxy {.wrap-anywhere}
{{< setting-metadata type="string" default="Empty string" >}}
@@ -1,15 +1,16 @@
---
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.
description: Route local sandbox, daemon, and host CLI traffic through an upstream proxy, including cloud connections, 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: 40
aliases:
- /ai/sandboxes/upstream-proxy/
---
This page describes proxy settings for local sandboxes and the local daemon.
For cloud sandbox egress controls, see
This page describes proxy settings for local sandboxes, the local daemon, and
host CLI connections to cloud sandboxes. These settings don't configure traffic
originating inside a cloud sandbox. For cloud sandbox egress controls, see
[Cloud network policy](../cloud/network-policy.md).
> [!IMPORTANT]
@@ -28,10 +29,10 @@ 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, including image pulls,
telemetry, and feature flags. CLI requests for `sbx login` and
`sbx diagnose --upload` also use this scope.
- Sandbox traffic — network access from inside your local sandboxes.
- Daemon and host CLI traffic — the daemon's own access, including image pulls,
telemetry, and feature flags, and host CLI requests, including `sbx login`,
`sbx diagnose --upload`, cloud commands, `sbx move`, the TUI, and cloud SSH.
## Default behavior
@@ -126,9 +127,8 @@ Proxy settings take effect at different times depending on the consumer:
- Daemon scope (`proxy.daemon`, `no_proxy.daemon`, and the daemon side of
`proxy` and `no_proxy`) is resolved once when the daemon starts. Changes to
the daemon's own traffic require `sbx daemon restart`.
- Supported CLI clients read daemon-scoped settings on each invocation,
including `sbx login` and `sbx diagnose --upload`. Changes apply on the next
invocation without a daemon restart.
- Host CLI clients read daemon-scoped settings on each invocation. Changes
apply on the next invocation without a daemon restart.
The `DOCKER_SANDBOXES_*` environment variables are a separate case. They control
sandbox traffic only, as described in
@@ -140,6 +140,21 @@ the variable and restart the daemon for the stored setting to take effect.
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.
## Cloud SSH
Cloud SSH uses the configured host proxy to connect to the SSH gateway. Some
proxies refuse connections to the gateway's SSH port. If your network permits
direct SSH connections, bypass the proxy for cloud SSH:
```console
$ sbx settings set proxy.sshDirect true
```
This setting skips the proxy entirely for cloud SSH, without trying it first.
Other host CLI requests keep using the configured proxy. The change applies on
the next SSH connection without a daemon restart. Set it to `false` to use the
proxy again.
## Authentication
If the upstream proxy requires you to authenticate to it, `sbx` supports two