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..7f06f6ee7d50 --- /dev/null +++ b/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 `.sbx`, where `` is the sandbox name. +Once SSH is set up, `.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 `.sbx` starts the sandbox if it isn't running. The sandbox +must already exist. diff --git a/content/manuals/ai/sandboxes/integrations/chatgpt.md b/content/manuals/ai/sandboxes/integrations/chatgpt.md new file mode 100644 index 000000000000..f6944a557e45 --- /dev/null +++ b/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 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..083b717329c6 --- /dev/null +++ b/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 diff --git a/content/manuals/ai/sandboxes/integrations/cursor.md b/content/manuals/ai/sandboxes/integrations/cursor.md new file mode 100644 index 000000000000..7b095d28879d --- /dev/null +++ b/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 `.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 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 diff --git a/content/manuals/ai/sandboxes/integrations/vscode.md b/content/manuals/ai/sandboxes/integrations/vscode.md new file mode 100644 index 000000000000..e4255754562d --- /dev/null +++ b/content/manuals/ai/sandboxes/integrations/vscode.md @@ -0,0 +1,59 @@ +--- +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, 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). + +## 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 diff --git a/data/summary.yaml b/data/summary.yaml index 1732712cbf5d..a7e97999d685 100644 --- a/data/summary.yaml +++ b/data/summary.yaml @@ -185,6 +185,9 @@ Docker Projects: availability: Beta Docker Sandboxes sbx: availability: Early Access +Docker Sandboxes SSH: + availability: Experimental + 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