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,127 @@
+---
+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, jetbrains, remote development, sbx
+params:
+  sidebar:
+    badge:
+      color: blue
+      text: Experimental
+---
+
+{{< 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, 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
+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.
+
+## 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 following commands to enable experimental features and SSH access:
+
+```console
+$ sbx settings set platform.allowExperimentalFeatures true
+$ sbx settings set feature.ssh true
+$ sbx daemon stop
+$ sbx setup ssh
+```
+
+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
+
+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
+```
+
+## Connect a specific tool
+
+- [VS Code](vscode.md)
+- [Cursor](cursor.md)
+- [JetBrains IDEs](jetbrains.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.

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

@@ -0,0 +1,52 @@
+---
+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 choose the sandbox 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,49 @@
+---
+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
+
+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
+
+- [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. Open a folder from the
+   sandbox workspace to start working.
+
+## 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/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