From 6eaeea5f86f0f9d871ea0c46565518a0ebbe4963 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 14 Jul 2026 09:24:25 +0200
Subject: [PATCH 01/17] docs(sandboxes): stub SSH editor and app integrations
 section

Add an experimental "Integrations" section documenting how to connect
external editors and apps to a sandbox over SSH. Includes an overview
page covering the SSH access model, enablement, and setup, plus thin
per-tool pages for VS Code, Cursor, Claude Desktop, and Codex.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 content/manuals/ai/sandboxes/_index.md        |   2 +
 .../ai/sandboxes/integrations/_index.md       | 129 ++++++++++++++++++
 .../sandboxes/integrations/claude-desktop.md  |  43 ++++++
 .../ai/sandboxes/integrations/codex.md        |  36 +++++
 .../ai/sandboxes/integrations/cursor.md       |  49 +++++++
 .../ai/sandboxes/integrations/vscode.md       |  43 ++++++
 data/summary.yaml                             |   2 +
 7 files changed, 304 insertions(+)
 create mode 100644 content/manuals/ai/sandboxes/integrations/_index.md
 create mode 100644 content/manuals/ai/sandboxes/integrations/claude-desktop.md
 create mode 100644 content/manuals/ai/sandboxes/integrations/codex.md
 create mode 100644 content/manuals/ai/sandboxes/integrations/cursor.md
 create mode 100644 content/manuals/ai/sandboxes/integrations/vscode.md

diff --git a/content/manuals/ai/sandboxes/_index.md b/content/manuals/ai/sandboxes/_index.md
index 75e419dc9984..674d9d069d5f 100644
--- a/content/manuals/ai/sandboxes/_index.md
+++ b/content/manuals/ai/sandboxes/_index.md
@@ -68,6 +68,8 @@ the [usage guide](usage.md) for common patterns.
 ## Learn more
 
 - [Agents](agents/) — supported agents and per-agent configuration
+- [Integrations](integrations/) — connect editors and apps like VS Code and
+  Cursor to a sandbox over SSH
 - [Customize](customize/) — reusable templates and declarative kits for
   extending or tailoring sandboxes
 - [Architecture](architecture.md) — microVM isolation, workspace mounting,
diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
new file mode 100644
index 000000000000..c730955dde1d
--- /dev/null
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -0,0 +1,129 @@
+---
+title: Editor and app integrations
+linkTitle: Integrations
+weight: 37
+description: Connect editors and desktop apps to a Docker Sandbox over SSH.
+keywords: docker sandboxes, ssh, integrations, vs code, cursor, remote development, sbx
+---
+
+{{< summary-bar feature_name="Docker Sandboxes SSH" >}}
+
+You can connect an external editor or desktop app to a running sandbox over
+SSH. This lets you use the tools you already know — VS Code, Cursor, Claude
+Desktop, and others — while your code runs, builds, and executes inside the
+isolated sandbox instead of on your host.
+
+Each sandbox is reachable at `<name>.sbx`, where `<name>` is the sandbox name.
+Once SSH is set up, `<name>.sbx` behaves like any other SSH host, so any tool
+that supports remote development over SSH can connect to it.
+
+> [!NOTE]
+> SSH access is experimental and off by default. The command surface and
+> behavior may change.
+
+## How it works
+
+`sbx setup ssh` writes a managed block to your `~/.ssh/config` that maps the
+`*.sbx` host pattern to the sandbox daemon. Connections don't use a network
+port or an SSH key:
+
+- A `ProxyCommand` relays the SSH stream to the daemon over its local socket
+  (a Unix domain socket on macOS and Linux, a named pipe on Windows).
+- The daemon accepts the connection only while you have an active Docker login.
+  Authentication is tied to your login, not to a stored key.
+- The host key is verified on every connection, so a rotated daemon key never
+  triggers a host-key mismatch.
+
+Because SSH terminates at the daemon, no SSH server runs inside the sandbox.
+Connecting to `<name>.sbx` starts the sandbox if it isn't running, and creates
+it first if it doesn't exist yet.
+
+## Prerequisites
+
+- The `sbx` CLI installed and signed in. See [Get started](../get-started.md).
+- An SSH client. macOS and most Linux distributions include OpenSSH. On
+  Windows, install the OpenSSH client.
+- The editor or app you want to connect, with its remote-over-SSH support
+  installed.
+
+## Enable SSH access
+
+SSH access is an experimental feature. Turn it on, restart the daemon so it
+picks up the setting, then write the SSH client config:
+
+```console
+$ sbx settings set platform.allowExperimentalFeatures true
+$ sbx settings set feature.ssh true
+$ sbx daemon stop && sbx daemon start
+$ sbx setup ssh
+```
+
+`sbx setup ssh` is idempotent — you can re-run it at any time. It adds a
+managed block to `~/.ssh/config` similar to the following:
+
+```text
+# >>> docker sandboxes (managed) >>>
+Host *.sbx
+    User _default_user_
+    ProxyCommand "sbx" ssh proxy %n
+    IdentityAgent none
+    IdentityFile /dev/null
+    IdentitiesOnly yes
+    ControlMaster no
+    ControlPath none
+    UserKnownHostsFile "~/.ssh/sbx_known_hosts"
+    KnownHostsCommand "sbx" ssh known-hosts %H
+    StrictHostKeyChecking yes
+    SendEnv *
+# <<< docker sandboxes (managed) <<<
+```
+
+You don't edit this block by hand. The `User _default_user_` sentinel tells the
+daemon to log you in as the sandbox image's default user, so your host username
+is never sent.
+
+## Connect
+
+Open a shell in a sandbox named `demo`:
+
+```console
+$ ssh demo.sbx
+```
+
+Connect as a specific user inside the sandbox:
+
+```console
+$ ssh root@demo.sbx
+```
+
+Transfer files with SFTP:
+
+```console
+$ sftp demo.sbx
+```
+
+## Revoke access
+
+Access is gated by your Docker login. To sever all SSH sessions, sign out:
+
+```console
+$ sbx logout
+```
+
+This stops the daemon and closes any live connections.
+
+## Limitations
+
+SSH access is experimental. The following limitations apply:
+
+- SFTP file transfer is supported on Linux hosts only.
+- Port forwarding is limited to the sandbox's loopback address. To expose a
+  sandbox port to your host, use
+  [`sbx ports`](../usage.md#accessing-services-in-the-sandbox) instead.
+
+## Connect a specific tool
+
+- [VS Code](vscode.md)
+- [Cursor](cursor.md)
+- [Claude Desktop](claude-desktop.md)
+- [Codex](codex.md)
diff --git a/content/manuals/ai/sandboxes/integrations/claude-desktop.md b/content/manuals/ai/sandboxes/integrations/claude-desktop.md
new file mode 100644
index 000000000000..120c88e73247
--- /dev/null
+++ b/content/manuals/ai/sandboxes/integrations/claude-desktop.md
@@ -0,0 +1,43 @@
+---
+title: Connect Claude Desktop to a sandbox
+linkTitle: Claude Desktop
+weight: 30
+description: Run Claude Code from Claude Desktop against a Docker Sandbox over SSH.
+keywords: docker sandboxes, claude desktop, claude code, remote ssh, sbx
+---
+
+{{< summary-bar feature_name="Docker Sandboxes SSH" >}}
+
+Claude Desktop can run Claude Code on a remote machine over SSH. Point it at a
+sandbox so the agent works inside the isolated environment instead of on your
+host.
+
+> [!NOTE]
+> This page covers Claude Desktop connecting to a sandbox over SSH. To run the
+> Claude Code CLI inside a sandbox directly, see
+> [Claude Code](../agents/claude-code.md).
+
+## Prerequisites
+
+- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access).
+- Claude Desktop installed.
+
+## Connect
+
+1. Open the environment picker and select **Add SSH host**.
+2. In the **Add SSH connection** dialog, enter the connection details:
+   - **Name**: a friendly label for the connection, such as `My sandbox`.
+   - **SSH Host**: the sandbox host, `<name>.sbx`.
+   - Leave **SSH Port** and **Identity File** empty. The managed SSH config
+     that `sbx setup ssh` wrote supplies everything else.
+3. Select **Add SSH connection**. Claude Desktop connects to the sandbox and
+   runs Claude Code there.
+
+<!-- TODO: add screenshots of the environment picker and the Add SSH connection dialog -->
+
+## Related
+
+- [Editor and app integrations](_index.md) — how SSH access works and how to
+  set it up
+- [Claude Code](../agents/claude-code.md) — run the Claude Code CLI inside a
+  sandbox
diff --git a/content/manuals/ai/sandboxes/integrations/codex.md b/content/manuals/ai/sandboxes/integrations/codex.md
new file mode 100644
index 000000000000..3ebf03d1fce8
--- /dev/null
+++ b/content/manuals/ai/sandboxes/integrations/codex.md
@@ -0,0 +1,36 @@
+---
+title: Connect Codex to a sandbox
+linkTitle: Codex
+weight: 40
+description: Run the Codex app against a Docker Sandbox over SSH.
+keywords: docker sandboxes, codex, openai, remote ssh, sbx
+---
+
+{{< summary-bar feature_name="Docker Sandboxes SSH" >}}
+
+Connect the Codex app to a sandbox over SSH so it works inside the isolated
+environment instead of on your host.
+
+> [!NOTE]
+> This page covers the Codex app connecting to a sandbox over SSH. To run the
+> Codex CLI inside a sandbox directly, see [Codex](../agents/codex.md).
+
+## Prerequisites
+
+- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access).
+- The Codex app installed.
+
+## Connect
+
+1. In the Codex app, add a new SSH connection.
+2. Enter the sandbox host, `<name>.sbx`. Leave port and identity settings
+   empty — the managed SSH config that `sbx setup ssh` wrote supplies them.
+3. Connect. Codex runs against the sandbox over SSH.
+
+<!-- TODO: confirm the exact Codex app connection flow and add screenshots -->
+
+## Related
+
+- [Editor and app integrations](_index.md) — how SSH access works and how to
+  set it up
+- [Codex](../agents/codex.md) — run the Codex CLI inside a sandbox
diff --git a/content/manuals/ai/sandboxes/integrations/cursor.md b/content/manuals/ai/sandboxes/integrations/cursor.md
new file mode 100644
index 000000000000..4b696f65688e
--- /dev/null
+++ b/content/manuals/ai/sandboxes/integrations/cursor.md
@@ -0,0 +1,49 @@
+---
+title: Connect Cursor to a sandbox
+linkTitle: Cursor
+weight: 20
+description: Use Cursor's Remote - SSH support to develop inside a Docker Sandbox.
+keywords: docker sandboxes, cursor, remote ssh, remote development, sbx
+---
+
+{{< summary-bar feature_name="Docker Sandboxes SSH" >}}
+
+Cursor is built on VS Code, so it connects to a sandbox the same way, using
+Remote - SSH. Your editor stays on your host while files, terminals, and
+extensions run in the isolated sandbox.
+
+> [!NOTE]
+> This page covers the Cursor editor connecting to a sandbox over SSH. To run
+> the Cursor agent CLI inside a sandbox instead, see
+> [Cursor agent](../agents/cursor.md).
+
+## Prerequisites
+
+- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access).
+- Cursor's Remote - SSH support installed. Cursor bundles a Remote - SSH
+  extension compatible with the VS Code one.
+
+## Connect
+
+1. Open the Command Palette and run **Remote-SSH: Connect to Host**.
+2. Select the sandbox host, `<name>.sbx`. Because `sbx setup ssh` added it to
+   your SSH config, it appears in the host list automatically. You can also
+   type it in directly.
+3. Cursor opens a new window connected to the sandbox. Open a folder from the
+   sandbox workspace to start working.
+
+<!-- TODO: add screenshot of the Cursor Remote-SSH host picker showing <name>.sbx -->
+
+## Notes
+
+- The first connection installs the editor server inside the sandbox, so it
+  can take a moment. Later connections are faster.
+- Port forwarding is limited to the sandbox's loopback address. To reach a
+  sandbox port from your host, use
+  [`sbx ports`](../usage.md#accessing-services-in-the-sandbox).
+
+## Related
+
+- [Editor and app integrations](_index.md) — how SSH access works and how to
+  set it up
+- [Cursor agent](../agents/cursor.md) — run the Cursor CLI inside a sandbox
diff --git a/content/manuals/ai/sandboxes/integrations/vscode.md b/content/manuals/ai/sandboxes/integrations/vscode.md
new file mode 100644
index 000000000000..8a54403ac5c4
--- /dev/null
+++ b/content/manuals/ai/sandboxes/integrations/vscode.md
@@ -0,0 +1,43 @@
+---
+title: Connect VS Code to a sandbox
+linkTitle: VS Code
+weight: 10
+description: Use VS Code Remote - SSH to develop inside a Docker Sandbox.
+keywords: docker sandboxes, vs code, remote ssh, remote development, sbx
+---
+
+{{< summary-bar feature_name="Docker Sandboxes SSH" >}}
+
+Use the Remote - SSH extension to open a VS Code window that runs inside a
+sandbox. Your editor stays on your host while files, terminals, and extensions
+run in the isolated sandbox.
+
+## Prerequisites
+
+- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access).
+- The [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
+  extension (`ms-vscode-remote.remote-ssh`) installed in VS Code.
+
+## Connect
+
+1. Open the Command Palette and run **Remote-SSH: Connect to Host**.
+2. Select the sandbox host, `<name>.sbx`. Because `sbx setup ssh` added it to
+   your SSH config, it appears in the host list automatically. You can also
+   type it in directly.
+3. VS Code opens a new window connected to the sandbox. Open a folder from the
+   sandbox workspace to start working.
+
+<!-- TODO: add screenshot of the Remote-SSH host picker showing <name>.sbx -->
+
+## Notes
+
+- The first connection installs the VS Code server inside the sandbox, so it
+  can take a moment. Later connections are faster.
+- Port forwarding is limited to the sandbox's loopback address. To reach a
+  sandbox port from your host, use
+  [`sbx ports`](../usage.md#accessing-services-in-the-sandbox).
+
+## Related
+
+- [Editor and app integrations](_index.md) — how SSH access works and how to
+  set it up
diff --git a/data/summary.yaml b/data/summary.yaml
index 1732712cbf5d..b441838a04b3 100644
--- a/data/summary.yaml
+++ b/data/summary.yaml
@@ -185,6 +185,8 @@ Docker Projects:
   availability: Beta
 Docker Sandboxes sbx:
   availability: Early Access
+Docker Sandboxes SSH:
+  availability: Experimental
 Docker Sandboxes:
   availability: Experimental
   requires: Docker Desktop [4.58](/manuals/desktop/release-notes.md#4580) or later

From 0d0b89c8e51e181f2d459be784289c429de45de3 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Tue, 14 Jul 2026 09:30:24 +0200
Subject: [PATCH 02/17] docs(sandboxes): fix SSH enablement steps to avoid
 foreground daemon

Bare `sbx daemon start` runs in the foreground and blocks the terminal.
Drop it in favor of `sbx daemon stop` plus background auto-start on the
next command, and note `sbx daemon start -d` as the explicit alternative.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 content/manuals/ai/sandboxes/integrations/_index.md | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index c730955dde1d..54357025cb09 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -48,16 +48,22 @@ it first if it doesn't exist yet.
 
 ## Enable SSH access
 
-SSH access is an experimental feature. Turn it on, restart the daemon so it
-picks up the setting, then write the SSH client config:
+SSH access is an experimental feature. Turn it on, then stop the daemon so it
+reloads with the new setting. The daemon reads `feature.ssh` only at startup,
+so the change takes effect the next time it starts:
 
 ```console
 $ sbx settings set platform.allowExperimentalFeatures true
 $ sbx settings set feature.ssh true
-$ sbx daemon stop && sbx daemon start
+$ sbx daemon stop
 $ sbx setup ssh
 ```
 
+The `sbx` CLI starts the daemon automatically in the background when a command
+needs it, so `sbx setup ssh` brings it back up with SSH enabled — you don't
+start it by hand. To start it yourself instead, use `sbx daemon start -d`; the
+`-d` flag runs it in the background rather than holding your terminal.
+
 `sbx setup ssh` is idempotent — you can re-run it at any time. It adds a
 managed block to `~/.ssh/config` similar to the following:
 

From 5df15a8e18061b4540195bd14ee205d43c9bff51 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 08:26:00 +0000
Subject: [PATCH 03/17] docs(sandboxes): clarify SSH integration setup

SSH integrations require an existing named sandbox, and wildcard SSH configuration does not enumerate sandbox hosts in application pickers.

Document manual host entry, the Codex template requirement, the VS Code macOS workaround, loopback forwarding behavior, and the v0.36.0 minimum version.
---
 .../ai/sandboxes/integrations/_index.md       | 30 +++++++++++++++----
 .../sandboxes/integrations/claude-desktop.md  |  2 +-
 .../ai/sandboxes/integrations/codex.md        | 18 +++++++----
 .../ai/sandboxes/integrations/cursor.md       |  9 ++----
 .../ai/sandboxes/integrations/vscode.md       | 24 +++++++++++----
 data/summary.yaml                             |  1 +
 6 files changed, 61 insertions(+), 23 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index 54357025cb09..8fd2ee3998e8 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -35,8 +35,8 @@ port or an SSH key:
   triggers a host-key mismatch.
 
 Because SSH terminates at the daemon, no SSH server runs inside the sandbox.
-Connecting to `<name>.sbx` starts the sandbox if it isn't running, and creates
-it first if it doesn't exist yet.
+Connecting to `<name>.sbx` starts the sandbox if it isn't running. The sandbox
+must already exist.
 
 ## Prerequisites
 
@@ -88,6 +88,27 @@ You don't edit this block by hand. The `User _default_user_` sentinel tells the
 daemon to log you in as the sandbox image's default user, so your host username
 is never sent.
 
+The wildcard entry configures how SSH clients connect, but it doesn't add
+individual sandbox names to application host pickers. Enter the sandbox
+hostname, such as `demo.sbx`, manually when you configure an integration.
+
+## Create or identify a sandbox
+
+SSH connections require an existing sandbox. To create a named shell sandbox
+for the current directory:
+
+```console
+$ sbx create --name demo shell .
+```
+
+To identify an existing sandbox, list your sandboxes:
+
+```console
+$ sbx ls
+```
+
+Use the sandbox name as the SSH hostname with the `.sbx` suffix.
+
 ## Connect
 
 Open a shell in a sandbox named `demo`:
@@ -123,9 +144,8 @@ This stops the daemon and closes any live connections.
 SSH access is experimental. The following limitations apply:
 
 - SFTP file transfer is supported on Linux hosts only.
-- Port forwarding is limited to the sandbox's loopback address. To expose a
-  sandbox port to your host, use
-  [`sbx ports`](../usage.md#accessing-services-in-the-sandbox) instead.
+- SSH port forwarding can reach services on the sandbox's loopback address.
+  Other destination addresses aren't supported.
 
 ## Connect a specific tool
 
diff --git a/content/manuals/ai/sandboxes/integrations/claude-desktop.md b/content/manuals/ai/sandboxes/integrations/claude-desktop.md
index 120c88e73247..c8ede8732930 100644
--- a/content/manuals/ai/sandboxes/integrations/claude-desktop.md
+++ b/content/manuals/ai/sandboxes/integrations/claude-desktop.md
@@ -27,7 +27,7 @@ host.
 1. Open the environment picker and select **Add SSH host**.
 2. In the **Add SSH connection** dialog, enter the connection details:
    - **Name**: a friendly label for the connection, such as `My sandbox`.
-   - **SSH Host**: the sandbox host, `<name>.sbx`.
+   - **SSH Host**: enter the sandbox host manually as `<name>.sbx`.
    - Leave **SSH Port** and **Identity File** empty. The managed SSH config
      that `sbx setup ssh` wrote supplies everything else.
 3. Select **Add SSH connection**. Claude Desktop connects to the sandbox and
diff --git a/content/manuals/ai/sandboxes/integrations/codex.md b/content/manuals/ai/sandboxes/integrations/codex.md
index 3ebf03d1fce8..8fca4b4ad828 100644
--- a/content/manuals/ai/sandboxes/integrations/codex.md
+++ b/content/manuals/ai/sandboxes/integrations/codex.md
@@ -19,15 +19,23 @@ environment instead of on your host.
 
 - SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access).
 - The Codex app installed.
+- An existing sandbox created from the Codex template. The template includes
+  the `codex` command required by the app's remote server.
 
 ## Connect
 
-1. In the Codex app, add a new SSH connection.
-2. Enter the sandbox host, `<name>.sbx`. Leave port and identity settings
-   empty — the managed SSH config that `sbx setup ssh` wrote supplies them.
-3. Connect. Codex runs against the sandbox over SSH.
+Create a named Codex sandbox for the current directory if you don't already
+have one:
 
-<!-- TODO: confirm the exact Codex app connection flow and add screenshots -->
+```console
+$ sbx create --name demo codex .
+```
+
+Follow the Codex instructions to
+[connect to an SSH host](https://learn.chatgpt.com/docs/remote-connections#connect-to-an-ssh-host).
+Add the connection manually and enter the sandbox hostname, such as `demo.sbx`,
+as the endpoint. Leave port and identity settings empty because the managed SSH
+config supplies them.
 
 ## Related
 
diff --git a/content/manuals/ai/sandboxes/integrations/cursor.md b/content/manuals/ai/sandboxes/integrations/cursor.md
index 4b696f65688e..733bd4f8b771 100644
--- a/content/manuals/ai/sandboxes/integrations/cursor.md
+++ b/content/manuals/ai/sandboxes/integrations/cursor.md
@@ -26,9 +26,7 @@ extensions run in the isolated sandbox.
 ## Connect
 
 1. Open the Command Palette and run **Remote-SSH: Connect to Host**.
-2. Select the sandbox host, `<name>.sbx`. Because `sbx setup ssh` added it to
-   your SSH config, it appears in the host list automatically. You can also
-   type it in directly.
+2. Enter the sandbox host manually as `<name>.sbx`.
 3. Cursor opens a new window connected to the sandbox. Open a folder from the
    sandbox workspace to start working.
 
@@ -38,9 +36,8 @@ extensions run in the isolated sandbox.
 
 - The first connection installs the editor server inside the sandbox, so it
   can take a moment. Later connections are faster.
-- Port forwarding is limited to the sandbox's loopback address. To reach a
-  sandbox port from your host, use
-  [`sbx ports`](../usage.md#accessing-services-in-the-sandbox).
+- SSH port forwarding can reach services on the sandbox's loopback address.
+  Other destination addresses aren't supported.
 
 ## Related
 
diff --git a/content/manuals/ai/sandboxes/integrations/vscode.md b/content/manuals/ai/sandboxes/integrations/vscode.md
index 8a54403ac5c4..e908f8451e97 100644
--- a/content/manuals/ai/sandboxes/integrations/vscode.md
+++ b/content/manuals/ai/sandboxes/integrations/vscode.md
@@ -21,9 +21,7 @@ run in the isolated sandbox.
 ## Connect
 
 1. Open the Command Palette and run **Remote-SSH: Connect to Host**.
-2. Select the sandbox host, `<name>.sbx`. Because `sbx setup ssh` added it to
-   your SSH config, it appears in the host list automatically. You can also
-   type it in directly.
+2. Enter the sandbox host manually as `<name>.sbx`.
 3. VS Code opens a new window connected to the sandbox. Open a folder from the
    sandbox workspace to start working.
 
@@ -33,9 +31,23 @@ run in the isolated sandbox.
 
 - The first connection installs the VS Code server inside the sandbox, so it
   can take a moment. Later connections are faster.
-- Port forwarding is limited to the sandbox's loopback address. To reach a
-  sandbox port from your host, use
-  [`sbx ports`](../usage.md#accessing-services-in-the-sandbox).
+- SSH port forwarding can reach services on the sandbox's loopback address.
+  Other destination addresses aren't supported.
+
+### Reconnect loop on macOS
+
+Affected versions of VS Code can enter an infinite reconnect loop on macOS. If
+this happens, set `remote.SSH.useLocalServer` to `false` in your VS Code user
+settings:
+
+```json
+{
+  "remote.SSH.useLocalServer": false
+}
+```
+
+For details, see
+[microsoft/vscode-remote-release#11672](https://github.com/microsoft/vscode-remote-release/issues/11672).
 
 ## Related
 
diff --git a/data/summary.yaml b/data/summary.yaml
index b441838a04b3..9741266d2871 100644
--- a/data/summary.yaml
+++ b/data/summary.yaml
@@ -187,6 +187,7 @@ Docker Sandboxes sbx:
   availability: Early Access
 Docker Sandboxes SSH:
   availability: Experimental
+  requires: Docker Sandboxes 0.36.0 or later
 Docker Sandboxes:
   availability: Experimental
   requires: Docker Desktop [4.58](/manuals/desktop/release-notes.md#4580) or later

From 03bc2d13d5f25e7ed5f1a40c414f96476d279c62 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 08:30:37 +0000
Subject: [PATCH 04/17] docs(sandboxes): move SSH forwarding guidance

The loopback forwarding constraint was too opaque in the integration overview and editor pages.

Move it to troubleshooting with a concrete local-forward example and explain when the unsupported destination case applies.
---
 .../manuals/ai/sandboxes/integrations/_index.md   |  2 --
 .../manuals/ai/sandboxes/integrations/cursor.md   |  2 --
 .../manuals/ai/sandboxes/integrations/vscode.md   |  2 --
 content/manuals/ai/sandboxes/troubleshooting.md   | 15 +++++++++++++++
 4 files changed, 15 insertions(+), 6 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index 8fd2ee3998e8..e25031efb1fb 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -144,8 +144,6 @@ This stops the daemon and closes any live connections.
 SSH access is experimental. The following limitations apply:
 
 - SFTP file transfer is supported on Linux hosts only.
-- SSH port forwarding can reach services on the sandbox's loopback address.
-  Other destination addresses aren't supported.
 
 ## Connect a specific tool
 
diff --git a/content/manuals/ai/sandboxes/integrations/cursor.md b/content/manuals/ai/sandboxes/integrations/cursor.md
index 733bd4f8b771..083ec330d89a 100644
--- a/content/manuals/ai/sandboxes/integrations/cursor.md
+++ b/content/manuals/ai/sandboxes/integrations/cursor.md
@@ -36,8 +36,6 @@ extensions run in the isolated sandbox.
 
 - The first connection installs the editor server inside the sandbox, so it
   can take a moment. Later connections are faster.
-- SSH port forwarding can reach services on the sandbox's loopback address.
-  Other destination addresses aren't supported.
 
 ## Related
 
diff --git a/content/manuals/ai/sandboxes/integrations/vscode.md b/content/manuals/ai/sandboxes/integrations/vscode.md
index e908f8451e97..9eb19dcf6056 100644
--- a/content/manuals/ai/sandboxes/integrations/vscode.md
+++ b/content/manuals/ai/sandboxes/integrations/vscode.md
@@ -31,8 +31,6 @@ run in the isolated sandbox.
 
 - The first connection installs the VS Code server inside the sandbox, so it
   can take a moment. Later connections are faster.
-- SSH port forwarding can reach services on the sandbox's loopback address.
-  Other destination addresses aren't supported.
 
 ### Reconnect loop on macOS
 
diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md
index 240f96256a2d..f5104a6003a7 100644
--- a/content/manuals/ai/sandboxes/troubleshooting.md
+++ b/content/manuals/ai/sandboxes/troubleshooting.md
@@ -84,6 +84,21 @@ If a request to `127.0.0.1` or a local network IP returns "connection refused"
 from inside a sandbox, the address is not reachable from within the sandbox VM.
 See [Accessing host services from a sandbox](usage.md#accessing-host-services-from-a-sandbox).
 
+## SSH port forwarding to another host fails
+
+SSH can forward a service running inside a sandbox to your host. For example,
+the following command makes port `3000` in the sandbox available at
+`localhost:3000` on your host:
+
+```console
+$ ssh -N -L 3000:127.0.0.1:3000 demo.sbx
+```
+
+SSH can't use the sandbox as a tunnel to another host. For example, forwarding
+to `database.example.com:5432` isn't supported. This restriction doesn't affect
+VS Code, Cursor, and similar tools, which forward connections to services they
+start inside the sandbox.
+
 ## Docker authentication failure
 
 If you see a message like `You are not authenticated to Docker`, your login

From 858eabe156fb492f13be60190163293d99456936 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 08:32:39 +0000
Subject: [PATCH 05/17] docs(sandboxes): clarify SSH port forwarding

The troubleshooting entry described SSH itself as forwarding a service, which obscured the user's action.

Describe port forwarding as a capability of the user's SSH connection and state its destination boundary directly.
---
 content/manuals/ai/sandboxes/troubleshooting.md | 15 ++++++++-------
 1 file changed, 8 insertions(+), 7 deletions(-)

diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md
index f5104a6003a7..02d141fa2d79 100644
--- a/content/manuals/ai/sandboxes/troubleshooting.md
+++ b/content/manuals/ai/sandboxes/troubleshooting.md
@@ -86,18 +86,19 @@ See [Accessing host services from a sandbox](usage.md#accessing-host-services-fr
 
 ## SSH port forwarding to another host fails
 
-SSH can forward a service running inside a sandbox to your host. For example,
-the following command makes port `3000` in the sandbox available at
-`localhost:3000` on your host:
+You can use an SSH connection to make a service running inside a sandbox
+available on your host. For example, the following command makes port `3000`
+in the sandbox available at `localhost:3000` on your host:
 
 ```console
 $ ssh -N -L 3000:127.0.0.1:3000 demo.sbx
 ```
 
-SSH can't use the sandbox as a tunnel to another host. For example, forwarding
-to `database.example.com:5432` isn't supported. This restriction doesn't affect
-VS Code, Cursor, and similar tools, which forward connections to services they
-start inside the sandbox.
+Port forwarding through this connection can only target services inside the
+sandbox. You can't use the sandbox as a tunnel to another host, such as
+`database.example.com:5432`. This restriction doesn't affect VS Code, Cursor,
+and similar tools, which forward connections to services they start inside the
+sandbox.
 
 ## Docker authentication failure
 

From fc29998a36fbbfcb00009a786fda1ea13bdbe7d0 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 08:34:05 +0000
Subject: [PATCH 06/17] docs(sandboxes): drop SSH forwarding note

Manual SSH port forwarding duplicates the sbx ports workflow and exposes an integration implementation detail without a useful user action.

Remove the troubleshooting entry and keep service publishing documented through sbx ports.
---
 content/manuals/ai/sandboxes/troubleshooting.md | 16 ----------------
 1 file changed, 16 deletions(-)

diff --git a/content/manuals/ai/sandboxes/troubleshooting.md b/content/manuals/ai/sandboxes/troubleshooting.md
index 02d141fa2d79..240f96256a2d 100644
--- a/content/manuals/ai/sandboxes/troubleshooting.md
+++ b/content/manuals/ai/sandboxes/troubleshooting.md
@@ -84,22 +84,6 @@ If a request to `127.0.0.1` or a local network IP returns "connection refused"
 from inside a sandbox, the address is not reachable from within the sandbox VM.
 See [Accessing host services from a sandbox](usage.md#accessing-host-services-from-a-sandbox).
 
-## SSH port forwarding to another host fails
-
-You can use an SSH connection to make a service running inside a sandbox
-available on your host. For example, the following command makes port `3000`
-in the sandbox available at `localhost:3000` on your host:
-
-```console
-$ ssh -N -L 3000:127.0.0.1:3000 demo.sbx
-```
-
-Port forwarding through this connection can only target services inside the
-sandbox. You can't use the sandbox as a tunnel to another host, such as
-`database.example.com:5432`. This restriction doesn't affect VS Code, Cursor,
-and similar tools, which forward connections to services they start inside the
-sandbox.
-
 ## Docker authentication failure
 
 If you see a message like `You are not authenticated to Docker`, your login

From 99a19200bb854ce257af805b7111c6b5ca29e1e4 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 08:36:14 +0000
Subject: [PATCH 07/17] docs(sandboxes): link Claude Desktop SSH guide

The draft repeated a stale Claude Desktop SSH label and left screenshot placeholders for a changing external UI.

Link to Anthropic's SSH session instructions and retain only the Docker-specific sandbox hostname and SSH config guidance.
---
 .../ai/sandboxes/integrations/claude-desktop.md   | 15 +++++----------
 1 file changed, 5 insertions(+), 10 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/claude-desktop.md b/content/manuals/ai/sandboxes/integrations/claude-desktop.md
index c8ede8732930..6b690f983434 100644
--- a/content/manuals/ai/sandboxes/integrations/claude-desktop.md
+++ b/content/manuals/ai/sandboxes/integrations/claude-desktop.md
@@ -24,16 +24,11 @@ host.
 
 ## Connect
 
-1. Open the environment picker and select **Add SSH host**.
-2. In the **Add SSH connection** dialog, enter the connection details:
-   - **Name**: a friendly label for the connection, such as `My sandbox`.
-   - **SSH Host**: enter the sandbox host manually as `<name>.sbx`.
-   - Leave **SSH Port** and **Identity File** empty. The managed SSH config
-     that `sbx setup ssh` wrote supplies everything else.
-3. Select **Add SSH connection**. Claude Desktop connects to the sandbox and
-   runs Claude Code there.
-
-<!-- TODO: add screenshots of the environment picker and the Add SSH connection dialog -->
+Follow the Claude Desktop instructions for
+[SSH sessions](https://code.claude.com/docs/en/desktop#ssh-sessions). When you
+add the connection, enter the sandbox hostname, such as `demo.sbx`, manually in
+the **SSH Host** field. Leave **SSH Port** and **Identity File** empty because
+the managed SSH config supplies them.
 
 ## Related
 

From 424140f51432d0d3dd1ba28b604d9c79ae56cc35 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 08:51:26 +0000
Subject: [PATCH 08/17] docs(sandboxes): align integration SSH steps

The VS Code and Cursor pages duplicated vendor UI instructions and retained screenshot placeholders, while the Codex page named settings not covered by its official guide.

Link to maintained vendor instructions where available, verify terminal access first, and keep only Docker-specific manual hostname guidance.
---
 content/manuals/ai/sandboxes/integrations/codex.md |  9 +++++++--
 .../manuals/ai/sandboxes/integrations/cursor.md    | 11 +++++++----
 .../manuals/ai/sandboxes/integrations/vscode.md    | 14 +++++++++-----
 3 files changed, 23 insertions(+), 11 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/codex.md b/content/manuals/ai/sandboxes/integrations/codex.md
index 8fca4b4ad828..500a9b67a43a 100644
--- a/content/manuals/ai/sandboxes/integrations/codex.md
+++ b/content/manuals/ai/sandboxes/integrations/codex.md
@@ -31,11 +31,16 @@ have one:
 $ sbx create --name demo codex .
 ```
 
+Confirm that you can connect to the sandbox from a terminal:
+
+```console
+$ ssh demo.sbx
+```
+
 Follow the Codex instructions to
 [connect to an SSH host](https://learn.chatgpt.com/docs/remote-connections#connect-to-an-ssh-host).
 Add the connection manually and enter the sandbox hostname, such as `demo.sbx`,
-as the endpoint. Leave port and identity settings empty because the managed SSH
-config supplies them.
+as the endpoint. The managed SSH config supplies the connection settings.
 
 ## Related
 
diff --git a/content/manuals/ai/sandboxes/integrations/cursor.md b/content/manuals/ai/sandboxes/integrations/cursor.md
index 083ec330d89a..7b095d28879d 100644
--- a/content/manuals/ai/sandboxes/integrations/cursor.md
+++ b/content/manuals/ai/sandboxes/integrations/cursor.md
@@ -20,18 +20,21 @@ extensions run in the isolated sandbox.
 ## Prerequisites
 
 - SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access).
-- Cursor's Remote - SSH support installed. Cursor bundles a Remote - SSH
-  extension compatible with the VS Code one.
+- Cursor's Remote - SSH support installed.
 
 ## Connect
 
+Confirm that you can connect to the sandbox from a terminal:
+
+```console
+$ ssh demo.sbx
+```
+
 1. Open the Command Palette and run **Remote-SSH: Connect to Host**.
 2. Enter the sandbox host manually as `<name>.sbx`.
 3. Cursor opens a new window connected to the sandbox. Open a folder from the
    sandbox workspace to start working.
 
-<!-- TODO: add screenshot of the Cursor Remote-SSH host picker showing <name>.sbx -->
-
 ## Notes
 
 - The first connection installs the editor server inside the sandbox, so it
diff --git a/content/manuals/ai/sandboxes/integrations/vscode.md b/content/manuals/ai/sandboxes/integrations/vscode.md
index 9eb19dcf6056..646710c7eaa4 100644
--- a/content/manuals/ai/sandboxes/integrations/vscode.md
+++ b/content/manuals/ai/sandboxes/integrations/vscode.md
@@ -20,12 +20,16 @@ run in the isolated sandbox.
 
 ## Connect
 
-1. Open the Command Palette and run **Remote-SSH: Connect to Host**.
-2. Enter the sandbox host manually as `<name>.sbx`.
-3. VS Code opens a new window connected to the sandbox. Open a folder from the
-   sandbox workspace to start working.
+Confirm that you can connect to the sandbox from a terminal:
 
-<!-- TODO: add screenshot of the Remote-SSH host picker showing <name>.sbx -->
+```console
+$ ssh demo.sbx
+```
+
+Follow the VS Code instructions to
+[connect to a remote host](https://code.visualstudio.com/docs/remote/ssh#_connect-to-a-remote-host).
+When prompted for the host, enter the sandbox hostname, such as `demo.sbx`,
+manually. The managed SSH config supplies the connection settings.
 
 ## Notes
 

From 442d8a3861c2d16167e1bc77c593764b0084b42d Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 09:01:10 +0000
Subject: [PATCH 09/17] docs(sandboxes): add integration happy paths

The integration pages depended too heavily on upstream instructions for the basic connection flow. Add the minimum product navigation and sandbox-specific values locally while retaining official guides for additional options.
---
 .../sandboxes/integrations/claude-desktop.md  | 21 ++++++++++++++-----
 .../ai/sandboxes/integrations/codex.md        |  8 ++++---
 .../ai/sandboxes/integrations/vscode.md       |  8 ++++---
 3 files changed, 26 insertions(+), 11 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/claude-desktop.md b/content/manuals/ai/sandboxes/integrations/claude-desktop.md
index 6b690f983434..083b717329c6 100644
--- a/content/manuals/ai/sandboxes/integrations/claude-desktop.md
+++ b/content/manuals/ai/sandboxes/integrations/claude-desktop.md
@@ -24,11 +24,22 @@ host.
 
 ## Connect
 
-Follow the Claude Desktop instructions for
-[SSH sessions](https://code.claude.com/docs/en/desktop#ssh-sessions). When you
-add the connection, enter the sandbox hostname, such as `demo.sbx`, manually in
-the **SSH Host** field. Leave **SSH Port** and **Identity File** empty because
-the managed SSH config supplies them.
+Confirm that you can connect to the sandbox from a terminal:
+
+```console
+$ ssh demo.sbx
+```
+
+In Claude Desktop, open the environment drop-down before starting a session and
+select **+ Add SSH connection**. Enter a name for the connection and enter the
+sandbox hostname, such as `demo.sbx`, in **SSH Host**. Leave **SSH Port** and
+**Identity File** empty because the managed SSH config supplies them.
+
+Select the connection from the environment drop-down and choose the sandbox
+workspace folder.
+
+For more connection options, see the Claude Desktop instructions for
+[SSH sessions](https://code.claude.com/docs/en/desktop#ssh-sessions).
 
 ## Related
 
diff --git a/content/manuals/ai/sandboxes/integrations/codex.md b/content/manuals/ai/sandboxes/integrations/codex.md
index 500a9b67a43a..c1320703d88a 100644
--- a/content/manuals/ai/sandboxes/integrations/codex.md
+++ b/content/manuals/ai/sandboxes/integrations/codex.md
@@ -37,10 +37,12 @@ Confirm that you can connect to the sandbox from a terminal:
 $ ssh demo.sbx
 ```
 
-Follow the Codex instructions to
+In the Codex app, open **Settings > Connections** and add an SSH connection
+manually. Enter the sandbox hostname, such as `demo.sbx`, as the host, then
+choose the sandbox workspace folder as the remote project.
+
+For more connection options, see the Codex instructions to
 [connect to an SSH host](https://learn.chatgpt.com/docs/remote-connections#connect-to-an-ssh-host).
-Add the connection manually and enter the sandbox hostname, such as `demo.sbx`,
-as the endpoint. The managed SSH config supplies the connection settings.
 
 ## Related
 
diff --git a/content/manuals/ai/sandboxes/integrations/vscode.md b/content/manuals/ai/sandboxes/integrations/vscode.md
index 646710c7eaa4..e4255754562d 100644
--- a/content/manuals/ai/sandboxes/integrations/vscode.md
+++ b/content/manuals/ai/sandboxes/integrations/vscode.md
@@ -26,10 +26,12 @@ Confirm that you can connect to the sandbox from a terminal:
 $ ssh demo.sbx
 ```
 
-Follow the VS Code instructions to
+In VS Code, open the Command Palette and run **Remote-SSH: Connect to Host...**.
+Enter the sandbox hostname, such as `demo.sbx`, manually. After VS Code
+connects, open the sandbox workspace folder.
+
+For more connection options, see the VS Code instructions to
 [connect to a remote host](https://code.visualstudio.com/docs/remote/ssh#_connect-to-a-remote-host).
-When prompted for the host, enter the sandbox hostname, such as `demo.sbx`,
-manually. The managed SSH config supplies the connection settings.
 
 ## Notes
 

From 4303277768b3cdb862f16f3d47905fbc9b47abd0 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 09:03:04 +0000
Subject: [PATCH 10/17] docs(sandboxes): rename Codex app integration

The desktop client is named ChatGPT, while Codex is the agent that runs against the remote project. Rename the integration page and update its wording while preserving Codex references for the template, CLI, and remote command.
---
 .../ai/sandboxes/integrations/_index.md       |  2 +-
 .../integrations/{codex.md => chatgpt.md}     | 27 ++++++++++---------
 2 files changed, 15 insertions(+), 14 deletions(-)
 rename content/manuals/ai/sandboxes/integrations/{codex.md => chatgpt.md} (50%)

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index e25031efb1fb..0e9b3b379d86 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -150,4 +150,4 @@ SSH access is experimental. The following limitations apply:
 - [VS Code](vscode.md)
 - [Cursor](cursor.md)
 - [Claude Desktop](claude-desktop.md)
-- [Codex](codex.md)
+- [ChatGPT](chatgpt.md)
diff --git a/content/manuals/ai/sandboxes/integrations/codex.md b/content/manuals/ai/sandboxes/integrations/chatgpt.md
similarity index 50%
rename from content/manuals/ai/sandboxes/integrations/codex.md
rename to content/manuals/ai/sandboxes/integrations/chatgpt.md
index c1320703d88a..f6944a557e45 100644
--- a/content/manuals/ai/sandboxes/integrations/codex.md
+++ b/content/manuals/ai/sandboxes/integrations/chatgpt.md
@@ -1,24 +1,25 @@
 ---
-title: Connect Codex to a sandbox
-linkTitle: Codex
+title: Connect ChatGPT to a sandbox
+linkTitle: ChatGPT
 weight: 40
-description: Run the Codex app against a Docker Sandbox over SSH.
-keywords: docker sandboxes, codex, openai, remote ssh, sbx
+description: Run Codex in the ChatGPT desktop app against a Docker Sandbox over SSH.
+keywords: docker sandboxes, chatgpt, codex, openai, remote ssh, sbx
 ---
 
 {{< summary-bar feature_name="Docker Sandboxes SSH" >}}
 
-Connect the Codex app to a sandbox over SSH so it works inside the isolated
-environment instead of on your host.
+Connect the ChatGPT desktop app to a sandbox over SSH so Codex works inside the
+isolated environment instead of on your host.
 
 > [!NOTE]
-> This page covers the Codex app connecting to a sandbox over SSH. To run the
-> Codex CLI inside a sandbox directly, see [Codex](../agents/codex.md).
+> This page covers running Codex in the ChatGPT desktop app connected to a
+> sandbox over SSH. To run the Codex CLI inside a sandbox directly, see
+> [Codex](../agents/codex.md).
 
 ## Prerequisites
 
 - SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access).
-- The Codex app installed.
+- The ChatGPT desktop app installed.
 - An existing sandbox created from the Codex template. The template includes
   the `codex` command required by the app's remote server.
 
@@ -37,11 +38,11 @@ Confirm that you can connect to the sandbox from a terminal:
 $ ssh demo.sbx
 ```
 
-In the Codex app, open **Settings > Connections** and add an SSH connection
-manually. Enter the sandbox hostname, such as `demo.sbx`, as the host, then
-choose the sandbox workspace folder as the remote project.
+In the ChatGPT desktop app, open **Settings > Connections** and add an SSH
+connection manually. Enter the sandbox hostname, such as `demo.sbx`, as the
+host, then choose the sandbox workspace folder as the remote project.
 
-For more connection options, see the Codex instructions to
+For more connection options, see the OpenAI instructions to
 [connect to an SSH host](https://learn.chatgpt.com/docs/remote-connections#connect-to-an-ssh-host).
 
 ## Related

From a681652fe9dcc7328c6ebcb6efd500d15cfc9da2 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 09:09:21 +0000
Subject: [PATCH 11/17] docs(sandboxes): simplify SSH connection guidance

The overview mixed the basic SSH workflow with custom-user, SFTP, and access-revocation details. Focus the page on connecting to a named sandbox and direct file-copy needs to the existing sbx cp documentation.
---
 .../ai/sandboxes/integrations/_index.md       | 36 +++----------------
 1 file changed, 5 insertions(+), 31 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index 0e9b3b379d86..11c26e92fc06 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -107,43 +107,17 @@ To identify an existing sandbox, list your sandboxes:
 $ sbx ls
 ```
 
-Use the sandbox name as the SSH hostname with the `.sbx` suffix.
+## Connect to a sandbox over SSH
 
-## Connect
-
-Open a shell in a sandbox named `demo`:
+Use the sandbox name with the `.sbx` suffix. For example, to connect to a
+sandbox named `demo`:
 
 ```console
 $ ssh demo.sbx
 ```
 
-Connect as a specific user inside the sandbox:
-
-```console
-$ ssh root@demo.sbx
-```
-
-Transfer files with SFTP:
-
-```console
-$ sftp demo.sbx
-```
-
-## Revoke access
-
-Access is gated by your Docker login. To sever all SSH sessions, sign out:
-
-```console
-$ sbx logout
-```
-
-This stops the daemon and closes any live connections.
-
-## Limitations
-
-SSH access is experimental. The following limitations apply:
-
-- SFTP file transfer is supported on Linux hosts only.
+To copy files that aren't part of a mounted workspace, use
+[`sbx cp`](../usage.md#copying-files-between-host-and-sandbox).
 
 ## Connect a specific tool
 

From 4f34b44a91656aac9c883df2304611bb13adf3e0 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 09:09:44 +0000
Subject: [PATCH 12/17] docs(sandboxes): keep SSH overview focused

The sbx cp cross-reference was unrelated to configuring or using SSH integrations. Remove it so the connection section covers only the SSH workflow.
---
 content/manuals/ai/sandboxes/integrations/_index.md | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index 11c26e92fc06..9c727e55dd25 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -116,9 +116,6 @@ sandbox named `demo`:
 $ ssh demo.sbx
 ```
 
-To copy files that aren't part of a mounted workspace, use
-[`sbx cp`](../usage.md#copying-files-between-host-and-sandbox).
-
 ## Connect a specific tool
 
 - [VS Code](vscode.md)

From cdd7430cabdb2d026e5a397b7794e5683f693f1a Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 09:28:09 +0000
Subject: [PATCH 13/17] docs(sandboxes): clarify SSH config paths

The SSH setup description named only the Unix-style config path despite supporting Windows. Describe the file as the SSH config, list its platform-specific paths once, and use the generic name afterward.
---
 content/manuals/ai/sandboxes/integrations/_index.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index 9c727e55dd25..d3be4dbd25f4 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -23,9 +23,10 @@ that supports remote development over SSH can connect to it.
 
 ## How it works
 
-`sbx setup ssh` writes a managed block to your `~/.ssh/config` that maps the
-`*.sbx` host pattern to the sandbox daemon. Connections don't use a network
-port or an SSH key:
+`sbx setup ssh` writes a managed block to your SSH config: `~/.ssh/config` on
+macOS and Linux, or `%USERPROFILE%\.ssh\config` on Windows. The block maps the
+`*.sbx` host pattern to the sandbox daemon. Connections don't use a network port
+or an SSH key:
 
 - A `ProxyCommand` relays the SSH stream to the daemon over its local socket
   (a Unix domain socket on macOS and Linux, a named pipe on Windows).
@@ -65,7 +66,7 @@ start it by hand. To start it yourself instead, use `sbx daemon start -d`; the
 `-d` flag runs it in the background rather than holding your terminal.
 
 `sbx setup ssh` is idempotent — you can re-run it at any time. It adds a
-managed block to `~/.ssh/config` similar to the following:
+managed block to your SSH config similar to the following:
 
 ```text
 # >>> docker sandboxes (managed) >>>

From ebdb120e911d67d3045cdd03bca1e527c0cb0e92 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 09:31:41 +0000
Subject: [PATCH 14/17] docs(sandboxes): streamline SSH setup flow

The overview presented implementation details before the connection workflow and overloaded the enablement section with generated config details. Lead with setup and connection steps, then consolidate the managed config and transport explanation in a final technical section.
---
 .../ai/sandboxes/integrations/_index.md       | 102 +++++++++---------
 1 file changed, 49 insertions(+), 53 deletions(-)

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index d3be4dbd25f4..4ca5cfa3d218 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -21,24 +21,6 @@ that supports remote development over SSH can connect to it.
 > SSH access is experimental and off by default. The command surface and
 > behavior may change.
 
-## How it works
-
-`sbx setup ssh` writes a managed block to your SSH config: `~/.ssh/config` on
-macOS and Linux, or `%USERPROFILE%\.ssh\config` on Windows. The block maps the
-`*.sbx` host pattern to the sandbox daemon. Connections don't use a network port
-or an SSH key:
-
-- A `ProxyCommand` relays the SSH stream to the daemon over its local socket
-  (a Unix domain socket on macOS and Linux, a named pipe on Windows).
-- The daemon accepts the connection only while you have an active Docker login.
-  Authentication is tied to your login, not to a stored key.
-- The host key is verified on every connection, so a rotated daemon key never
-  triggers a host-key mismatch.
-
-Because SSH terminates at the daemon, no SSH server runs inside the sandbox.
-Connecting to `<name>.sbx` starts the sandbox if it isn't running. The sandbox
-must already exist.
-
 ## Prerequisites
 
 - The `sbx` CLI installed and signed in. See [Get started](../get-started.md).
@@ -49,9 +31,7 @@ must already exist.
 
 ## Enable SSH access
 
-SSH access is an experimental feature. Turn it on, then stop the daemon so it
-reloads with the new setting. The daemon reads `feature.ssh` only at startup,
-so the change takes effect the next time it starts:
+Run the following commands to enable experimental features and SSH access:
 
 ```console
 $ sbx settings set platform.allowExperimentalFeatures true
@@ -60,38 +40,9 @@ $ sbx daemon stop
 $ sbx setup ssh
 ```
 
-The `sbx` CLI starts the daemon automatically in the background when a command
-needs it, so `sbx setup ssh` brings it back up with SSH enabled — you don't
-start it by hand. To start it yourself instead, use `sbx daemon start -d`; the
-`-d` flag runs it in the background rather than holding your terminal.
-
-`sbx setup ssh` is idempotent — you can re-run it at any time. It adds a
-managed block to your SSH config similar to the following:
-
-```text
-# >>> docker sandboxes (managed) >>>
-Host *.sbx
-    User _default_user_
-    ProxyCommand "sbx" ssh proxy %n
-    IdentityAgent none
-    IdentityFile /dev/null
-    IdentitiesOnly yes
-    ControlMaster no
-    ControlPath none
-    UserKnownHostsFile "~/.ssh/sbx_known_hosts"
-    KnownHostsCommand "sbx" ssh known-hosts %H
-    StrictHostKeyChecking yes
-    SendEnv *
-# <<< docker sandboxes (managed) <<<
-```
-
-You don't edit this block by hand. The `User _default_user_` sentinel tells the
-daemon to log you in as the sandbox image's default user, so your host username
-is never sent.
-
-The wildcard entry configures how SSH clients connect, but it doesn't add
-individual sandbox names to application host pickers. Enter the sandbox
-hostname, such as `demo.sbx`, manually when you configure an integration.
+Stopping the daemon makes it reload the SSH setting the next time it starts.
+`sbx setup ssh` starts the daemon again and configures your SSH client. You can
+re-run the setup command at any time.
 
 ## Create or identify a sandbox
 
@@ -123,3 +74,48 @@ $ ssh demo.sbx
 - [Cursor](cursor.md)
 - [Claude Desktop](claude-desktop.md)
 - [ChatGPT](chatgpt.md)
+
+## How SSH connections work
+
+`sbx setup ssh` writes a managed block to your SSH config: `~/.ssh/config` on
+macOS and Linux, or `%USERPROFILE%\.ssh\config` on Windows. The block is similar
+to the following:
+
+```text
+# >>> docker sandboxes (managed) >>>
+Host *.sbx
+    User _default_user_
+    ProxyCommand "sbx" ssh proxy %n
+    IdentityAgent none
+    IdentityFile /dev/null
+    IdentitiesOnly yes
+    ControlMaster no
+    ControlPath none
+    UserKnownHostsFile "~/.ssh/sbx_known_hosts"
+    KnownHostsCommand "sbx" ssh known-hosts %H
+    StrictHostKeyChecking yes
+    SendEnv *
+# <<< docker sandboxes (managed) <<<
+```
+
+You don't edit this block by hand. The `User _default_user_` sentinel tells the
+daemon to log you in as the sandbox image's default user, so your host username
+is never sent.
+
+The `*.sbx` wildcard maps sandbox hostnames to the sandbox daemon, but it
+doesn't add individual sandbox names to application host pickers. Enter the
+sandbox hostname, such as `demo.sbx`, manually when you configure an
+integration.
+
+Connections don't use a network port or an SSH key:
+
+- A `ProxyCommand` relays the SSH stream to the daemon over its local socket
+  (a Unix domain socket on macOS and Linux, a named pipe on Windows).
+- The daemon accepts the connection only while you have an active Docker login.
+  Authentication is tied to your login, not to a stored key.
+- The host key is verified on every connection, so a rotated daemon key never
+  triggers a host-key mismatch.
+
+Because SSH terminates at the daemon, no SSH server runs inside the sandbox.
+Connecting to `<name>.sbx` starts the sandbox if it isn't running. The sandbox
+must already exist.

From 77a038a3392be11fc784c7302f9b1157e2f6e340 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Thu, 16 Jul 2026 13:45:20 +0000
Subject: [PATCH 15/17] docs(sandboxes): badge SSH integrations as experimental

The sidebar did not communicate that SSH-based editor and app integrations are experimental. Add the standard experimental badge metadata to the integrations entry.
---
 content/manuals/ai/sandboxes/integrations/_index.md | 5 +++++
 1 file changed, 5 insertions(+)

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index 4ca5cfa3d218..0aab68095fff 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -4,6 +4,11 @@ linkTitle: Integrations
 weight: 37
 description: Connect editors and desktop apps to a Docker Sandbox over SSH.
 keywords: docker sandboxes, ssh, integrations, vs code, cursor, remote development, sbx
+params:
+  sidebar:
+    badge:
+      color: blue
+      text: Experimental
 ---
 
 {{< summary-bar feature_name="Docker Sandboxes SSH" >}}

From 6d9abaf0d110624e243a275315cc6649937fd222 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 17 Jul 2026 11:54:14 +0000
Subject: [PATCH 16/17] docs(sandboxes): add JetBrains SSH integration

The SSH integration docs did not cover JetBrains Remote Development or its additional network requirements. Add the Gateway connection flow, required policy rules, and navigation entry using JetBrains' managed OpenSSH configuration support.
---
 .../ai/sandboxes/integrations/_index.md       |  9 +--
 .../ai/sandboxes/integrations/jetbrains.md    | 60 +++++++++++++++++++
 2 files changed, 65 insertions(+), 4 deletions(-)
 create mode 100644 content/manuals/ai/sandboxes/integrations/jetbrains.md

diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md
index 0aab68095fff..7f06f6ee7d50 100644
--- a/content/manuals/ai/sandboxes/integrations/_index.md
+++ b/content/manuals/ai/sandboxes/integrations/_index.md
@@ -3,7 +3,7 @@ title: Editor and app integrations
 linkTitle: Integrations
 weight: 37
 description: Connect editors and desktop apps to a Docker Sandbox over SSH.
-keywords: docker sandboxes, ssh, integrations, vs code, cursor, remote development, sbx
+keywords: docker sandboxes, ssh, integrations, vs code, cursor, jetbrains, remote development, sbx
 params:
   sidebar:
     badge:
@@ -14,9 +14,9 @@ params:
 {{< summary-bar feature_name="Docker Sandboxes SSH" >}}
 
 You can connect an external editor or desktop app to a running sandbox over
-SSH. This lets you use the tools you already know — VS Code, Cursor, Claude
-Desktop, and others — while your code runs, builds, and executes inside the
-isolated sandbox instead of on your host.
+SSH. This lets you use the tools you already know — VS Code, Cursor, JetBrains
+IDEs, Claude Desktop, and others — while your code runs, builds, and executes
+inside the isolated sandbox instead of on your host.
 
 Each sandbox is reachable at `<name>.sbx`, where `<name>` is the sandbox name.
 Once SSH is set up, `<name>.sbx` behaves like any other SSH host, so any tool
@@ -77,6 +77,7 @@ $ ssh demo.sbx
 
 - [VS Code](vscode.md)
 - [Cursor](cursor.md)
+- [JetBrains IDEs](jetbrains.md)
 - [Claude Desktop](claude-desktop.md)
 - [ChatGPT](chatgpt.md)
 
diff --git a/content/manuals/ai/sandboxes/integrations/jetbrains.md b/content/manuals/ai/sandboxes/integrations/jetbrains.md
new file mode 100644
index 000000000000..c38cbd0861b2
--- /dev/null
+++ b/content/manuals/ai/sandboxes/integrations/jetbrains.md
@@ -0,0 +1,60 @@
+---
+title: Connect a JetBrains IDE to a sandbox
+linkTitle: JetBrains IDEs
+weight: 25
+description: Use JetBrains Remote Development to develop inside a Docker Sandbox over SSH.
+keywords: docker sandboxes, jetbrains, remote development, remote ssh, gateway, sbx
+---
+
+{{< summary-bar feature_name="Docker Sandboxes SSH" >}}
+
+JetBrains Remote Development runs the IDE backend inside the sandbox and opens
+the project locally in JetBrains Client. Connect through JetBrains Gateway or
+the Remote Development option in a supported JetBrains IDE.
+
+## Prerequisites
+
+- SSH access set up. See [Editor and app integrations](_index.md#enable-ssh-access).
+- [JetBrains Gateway installed](https://www.jetbrains.com/help/idea/jetbrains-gateway.html),
+  or a supported JetBrains IDE with the Remote Development Gateway plugin.
+
+## Allow JetBrains network access
+
+JetBrains Gateway downloads the IDE backend into the sandbox. The Balanced
+network preset doesn't include all the required JetBrains endpoints. Add a
+sandbox-scoped rule for them:
+
+```console
+$ sbx policy allow network --sandbox demo "*.jetbrains.com,data.services.jetbrains.com"
+```
+
+If your organization manages sandbox network policy, ask your administrator to
+allow these endpoints instead. Organization policy overrides local rules.
+
+## Connect
+
+Confirm that you can connect to the sandbox from a terminal:
+
+```console
+$ ssh demo.sbx
+```
+
+1. Open JetBrains Gateway. Alternatively, select **Remote Development** from
+   the welcome screen of a supported JetBrains IDE.
+2. Under **SSH Connection**, select **New Connection**.
+3. Create an SSH configuration with `demo.sbx` as the host and select
+   **OpenSSH config and authentication agent** as the authentication type. The
+   managed SSH config supplies the remaining connection settings.
+4. Select **Check Connection and Continue**.
+5. Choose the backend IDE version and the project folder in the sandbox, then
+   connect. The first connection downloads and installs the IDE backend inside
+   the sandbox.
+
+For more connection options, see the JetBrains instructions to
+[connect and work with JetBrains Gateway](https://www.jetbrains.com/help/idea/remote-development-a.html).
+
+## Related
+
+- [Editor and app integrations](_index.md) — how SSH access works and how to
+  set it up
+- [Local policy](../governance/local.md) — manage sandbox network access

From 713383ce6a73ed30490948b2a2d26cad07739e93 Mon Sep 17 00:00:00 2001
From: David Karlsson <35727626+dvdksn@users.noreply.github.com>
Date: Fri, 17 Jul 2026 13:19:31 +0000
Subject: [PATCH 17/17] docs(sandboxes): require SSH version 0.37

Docker Sandboxes 0.36.0 was not released, so it cannot be the SSH feature's minimum version. Update the summary metadata to require Docker Sandboxes 0.37.0 or later.
---
 data/summary.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/data/summary.yaml b/data/summary.yaml
index 9741266d2871..a7e97999d685 100644
--- a/data/summary.yaml
+++ b/data/summary.yaml
@@ -187,7 +187,7 @@ Docker Sandboxes sbx:
   availability: Early Access
 Docker Sandboxes SSH:
   availability: Experimental
-  requires: Docker Sandboxes 0.36.0 or later
+  requires: Docker Sandboxes 0.37.0 or later
 Docker Sandboxes:
   availability: Experimental
   requires: Docker Desktop [4.58](/manuals/desktop/release-notes.md#4580) or later