From 63b70a9b3687567200a4aef2695ac8bff3209fce Mon Sep 17 00:00:00 2001 From: David Karlsson <35727626+dvdksn@users.noreply.github.com> Date: Tue, 20 Oct 2026 08:10:52 +0000 Subject: [PATCH] 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. --- content/manuals/ai/sandboxes/cloud/usage.md | 3 ++ .../ai/sandboxes/configuration/settings.md | 13 +++++-- .../sandboxes/configuration/upstream-proxy.md | 35 +++++++++++++------ 3 files changed, 39 insertions(+), 12 deletions(-) diff --git a/content/manuals/ai/sandboxes/cloud/usage.md b/content/manuals/ai/sandboxes/cloud/usage.md index c9dd9139ee..716312b1d6 100644 --- a/content/manuals/ai/sandboxes/cloud/usage.md +++ b/content/manuals/ai/sandboxes/cloud/usage.md @@ -131,6 +131,9 @@ $ ssh sbx_01abc123@sbx_cloud Replace the example with `ssh @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 diff --git a/content/manuals/ai/sandboxes/configuration/settings.md b/content/manuals/ai/sandboxes/configuration/settings.md index fbec7fc851..7fae3571fa 100644 --- a/content/manuals/ai/sandboxes/configuration/settings.md +++ b/content/manuals/ai/sandboxes/configuration/settings.md @@ -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" >}} diff --git a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md index 2f49630c80..93514fe688 100644 --- a/content/manuals/ai/sandboxes/configuration/upstream-proxy.md +++ b/content/manuals/ai/sandboxes/configuration/upstream-proxy.md @@ -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