sbx: SSH and app integrations#25557
Conversation
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>
✅ Deploy Preview for docsdocker ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
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>
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.
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.
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.
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.
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.
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.
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.
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.
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.
The sbx cp cross-reference was unrelated to configuring or using SSH integrations. Remove it so the connection section covers only the SSH workflow.
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.
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.
The sidebar did not communicate that SSH-based editor and app integrations are experimental. Add the standard experimental badge metadata to the integrations entry.
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.
dvdksn
changed the title
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.
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
Four medium findings in newly added content: an unverified CLI argument syntax for the JetBrains network policy command, two external links pointing to non-standard domains that may not resolve, and an undocumented SendEnv * directive in the managed SSH config block that silently forwards all host environment variables into the sandbox.
| sandbox-scoped rule for them: | ||
|
|
||
| ```console | ||
| $ sbx policy allow network --sandbox demo "*.jetbrains.com,data.services.jetbrains.com" |
There was a problem hiding this comment.
[MEDIUM] Network policy command passes two hostnames as a single comma-delimited string
The command as documented is:
$ sbx policy allow network --sandbox demo "*.jetbrains.com,data.services.jetbrains.com"This passes both hostnames as one quoted string argument. If the sbx CLI doesn't parse comma-separated values, it will treat *.jetbrains.com,data.services.jetbrains.com as a literal hostname and create no useful rule for either endpoint.
If the CLI expects separate arguments, the correct form would be:
$ sbx policy allow network --sandbox demo "*.jetbrains.com" "data.services.jetbrains.com"Please verify the CLI's argument syntax and update the command accordingly.
| 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). |
There was a problem hiding this comment.
[MEDIUM] External link uses an unverified domain (learn.chatgpt.com)
The link points to:
https://learn.chatgpt.com/docs/remote-connections#connect-to-an-ssh-host
The standard OpenAI help domain is help.openai.com. The learn.chatgpt.com subdomain is unusual — if it doesn't exist or doesn't host this page, users will get a 404. Please verify the URL resolves and the anchor #connect-to-an-ssh-host exists before publishing.
| workspace folder. | ||
|
|
||
| For more connection options, see the Claude Desktop instructions for | ||
| [SSH sessions](https://code.claude.com/docs/en/desktop#ssh-sessions). |
There was a problem hiding this comment.
[MEDIUM] External link uses an unverified domain (code.claude.com)
The link points to:
https://code.claude.com/docs/en/desktop#ssh-sessions
Standard Anthropic documentation lives at docs.anthropic.com. The code.claude.com domain is unverified — if it doesn't resolve or doesn't contain this section, users will hit a broken link. Please confirm the URL and anchor #ssh-sessions are valid before publishing.
| UserKnownHostsFile "~/.ssh/sbx_known_hosts" | ||
| KnownHostsCommand "sbx" ssh known-hosts %H | ||
| StrictHostKeyChecking yes | ||
| SendEnv * |
There was a problem hiding this comment.
[MEDIUM] SendEnv * silently forwards all host environment variables — not explained in prose
The managed SSH config block includes SendEnv *, which sends every environment variable from the host shell into the sandbox. Users who store API keys, tokens, or other secrets in their environment (e.g., OPENAI_API_KEY, AWS_SECRET_ACCESS_KEY) will have those forwarded without realising it.
The surrounding explanation covers User _default_user_ and the *.sbx wildcard but says nothing about SendEnv *. Consider adding a short note, for example:
SendEnv *forwards your shell environment variables into the sandbox. Avoid storing sensitive secrets directly in your shell environment, or unset them before connecting.
docker-agent
left a comment
docker-agent
left a comment
There was a problem hiding this comment.
Assessment: 🟡 NEEDS ATTENTION
Two issues found in the new SSH integration documentation — one wording ambiguity and one missing step. Everything else looks clean: front matter is complete, shortcode syntax is correct, no AI-isms (hedge words, 'allows you to', 'in order to'), bold used only for UI elements, and no missing redirects (only new pages added).
| 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 |
There was a problem hiding this comment.
[MEDIUM] Contradictory statements about sandbox auto-start behavior
The paragraph reads:
Connecting to
<name>.sbxstarts the sandbox if it isn't running. The sandbox must already exist.
The first sentence says connecting auto-starts the sandbox; the second says it must already exist. A reader unfamiliar with the sandbox lifecycle will not know whether "must already exist" means:
- The sandbox must be created (but can be stopped — auto-start applies), or
- The sandbox must already be running
The technical distinction is valid, but it needs to be spelled out. Consider rephrasing:
The sandbox must already be created. If it is stopped, connecting starts it automatically.
|
|
||
| ## Connect | ||
|
|
||
| Confirm that you can connect to the sandbox from a terminal: |
There was a problem hiding this comment.
[MEDIUM] Missing sandbox creation step before SSH test
The Connect section asks users to confirm they can connect (ssh demo.sbx), but the Prerequisites only cover SSH setup and Claude Desktop installation — there is no step to create a sandbox named demo first.
Compare with chatgpt.md, which explicitly includes:
$ sbx create --name demo codex .A user arriving at this page directly (e.g., from search) would not know they need to create a sandbox before testing the SSH connection. Adding a sbx create step or a link to the "Create or identify a sandbox" section of the parent page would close this gap.
3 participants
What
Stubs a new experimental Integrations section under
content/manuals/ai/sandboxes/documenting how to connect external editors andapps to a sandbox over SSH.
https://deploy-preview-25557--docsdocker.netlify.app/ai/sandboxes/integrations/
🤖 Generated with Claude Code