sbx: SSH and app integrations

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,

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

@@ -0,0 +1,130 @@
+---
+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.
+
+## 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
+
+Run the SSH setup command once:
+
+```console
+$ sbx setup ssh
+```
+
+The command starts the Docker Sandboxes daemon if needed and configures your
+SSH client. You can re-run it at any time.
+
+## 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
+```
+
+## Connect to a sandbox over SSH
+
+Use the sandbox name with the `.sbx` suffix. For example, to connect to a
+sandbox named `demo`:
+
+```console
+$ ssh demo.sbx
+```
+
+## Select the workspace folder
+
+Connecting an app to a sandbox selects the remote environment, but it might not
+open the mounted workspace automatically. Use the app's remote folder picker to
+select the workspace when you configure the connection or start a session.
+
+The folder picker might open at the sandbox user's home directory, typically
+`/home/agent`. Workspaces retain their absolute host paths inside the sandbox.
+For example, if you mount `/Users/bob/src/my-project`, select
+`/Users/bob/src/my-project` in the remote folder picker.
+
+## Connect a specific tool
+
+- [VS Code](vscode.md)
+- [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.
+
+`SendEnv *` offers host environment variables to the daemon, but the daemon
+accepts only variables in its `ssh.acceptEnv` allowlist. Execution-sensitive
+variables such as `PATH`, `LD_*`, and `NODE_OPTIONS` are always blocked, even
+if added to the allowlist. Accepted values apply only to the SSH session and
+aren't stored in the sandbox configuration.
+
+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.
+The sandbox must already be created. If it is stopped, connecting to
+`<name>.sbx` starts it automatically.

content/manuals/ai/sandboxes/integrations/chatgpt.md

@@ -0,0 +1,54 @@
+---
+title: Connect ChatGPT to a sandbox
+linkTitle: ChatGPT
+weight: 40
+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 ChatGPT desktop app to a sandbox over SSH so Codex works inside the
+isolated environment instead of on your host.
+
+> [!NOTE]
+> 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 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.
+
+## Connect
+
+Create a named Codex sandbox for the current directory if you don't already
+have one:
+
+```console
+$ sbx create --name demo codex .
+```
+
+Confirm that you can connect to the sandbox from a terminal:
+
+```console
+$ ssh demo.sbx
+```
+
+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 use the remote folder picker to
+[select the mounted workspace](_index.md#select-the-workspace-folder) as the
+remote project.
+
+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
+
+- [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

content/manuals/ai/sandboxes/integrations/claude-desktop.md

@@ -0,0 +1,69 @@
+---
+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).
+- An existing named sandbox. See
+  [Create or identify a sandbox](_index.md#create-or-identify-a-sandbox).
+- Claude Desktop installed.
+
+## Connect
+
+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, then use the remote
+folder picker to
+[select the mounted workspace](_index.md#select-the-workspace-folder). The
+picker might initially open at `/home/agent`.
+
+For more connection options, see the Claude Desktop instructions for
+[SSH sessions](https://code.claude.com/docs/en/desktop#ssh-sessions).
+
+## Troubleshoot SSH connection timeouts on Windows
+
+Claude Desktop requires Git on Windows. If an SSH connection times out and the
+Claude Desktop logs include `ProxyCommand error: spawn sh ENOENT`, install
+[Git for Windows](https://git-scm.com/download/win).
+
+If Git is already installed, verify that `sh.exe` is available on your `PATH`:
+
+```powershell
+PS> where.exe sh
+```
+
+If the command doesn't find `sh.exe`, add the Git `bin` directory to your user
+`Path`. The default directory is `C:\Program Files\Git\bin`. Quit and restart
+Claude Desktop after updating `Path`.
+
+## 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

content/manuals/ai/sandboxes/integrations/cursor.md

@@ -0,0 +1,47 @@
+---
+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.
+
+## 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. Use the remote folder
+   picker to [select the mounted workspace](_index.md#select-the-workspace-folder).
+
+## Notes
+
+- The first connection installs the editor server inside the sandbox, so it
+  can take a moment. Later connections are faster.
+
+## 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

content/manuals/ai/sandboxes/integrations/vscode.md

@@ -0,0 +1,60 @@
+---
+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
+
+Confirm that you can connect to the sandbox from a terminal:
+
+```console
+$ ssh demo.sbx
+```
+
+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, use the remote folder picker to
+[select the mounted workspace](_index.md#select-the-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).
+
+## Notes
+
+- The first connection installs the VS Code server inside the sandbox, so it
+  can take a moment. Later connections are faster.
+
+### 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
+
+- [Editor and app integrations](_index.md) — how SSH access works and how to
+  set it up

data/summary.yaml

@@ -185,6 +185,9 @@ Docker Projects:
   availability: Beta
 Docker Sandboxes sbx:
   availability: Early Access
+Docker Sandboxes SSH:
+  availability: GA
+  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