Connecting to sbx sandboxes

SSH access is experimental as of 0.37.0. It gives any SSH-capable tool a target — <name>.sbx — that behaves like a normal remote host, without a sbx exec shim or copy step in between. No SSH server actually runs inside the sandbox: the connection terminates at the local sbx daemon, which relays the stream into the container. That's why there's no key to manage and no port to open.

This is a distinct SSH mechanism from the one in running-sbx-sandboxes for forwarding your host SSH agent into a sandbox for commit signing. That one carries a signing key out to the sandbox for git to use. This one carries a remote-development client's UI session in. Same protocol, opposite purpose — don't let the shared vocabulary conflate them.

Enable it once

$ sbx setup ssh

This starts the daemon if needed and writes a managed block to your SSH config (~/.ssh/config, or %USERPROFILE%\.ssh\config on Windows). Re-run it any time; it's idempotent. From 0.38.0 it also warns if ssh isn't on PATH, or — on Windows — if sh isn't, since Claude Desktop's ProxyCommand shells out to sh.

Don't hand-edit the managed block. It maps Host *.sbx to sbx ssh proxy, and the wildcard means apps that auto-discover SSH hosts from your config won't list individual sandbox names — you always type <name>.sbx in by hand.

What <name>.sbx actually is

• No TCP port and no SSH key. ProxyCommand relays the stream over a local Unix socket (a named pipe on Windows). Authentication rides on your active sbx/Docker login, not a stored credential — sign out and the host stops answering.

• The host key is re-verified every connection, so a daemon restart or reinstall never produces a stale host-key mismatch the way a long-lived remote would.

• Connecting to a stopped sandbox starts it. You still need the sandbox to exist first — SSH doesn't create one:

  $ sbx create --name demo shell .
  $ ssh demo.sbx

• sbx rm refuses on a sandbox with an open SSH session (or SFTP transfer) unless you pass --force.

Environment variables don't cross by default

Before 0.37.1, an SSH session forwarded the connecting client's environment into the sandbox, which meant anything sitting in your shell — including ANTHROPIC_API_KEY, OPENAI_API_KEY, GH_TOKEN — landed inside the box too. 0.37.1 (2026-07-29) turned this off by default. The daemon still acknowledges SSH environment-forwarding requests for client compatibility, but now ignores every name and value. Nothing crosses unless you name it explicitly with the ssh.acceptEnv setting. Treat any variable you add there as something the sandbox can now read — don't opt in credential names as a reflex fix for a tool that expects its usual environment.

The Claude Desktop credential warning is separate from the above

Claude Desktop's SSH integration transmits Anthropic credentials into the Claude Code process running inside the sandbox as a normal part of how it works — this is app-level credential injection, not SSH client env-var forwarding, so the 0.37.1 fix above doesn't touch it. Docker's own docs flag it explicitly: connecting Claude Desktop to a sandbox over SSH reduces isolation guarantees, because the sandbox now holds a real credential instead of the proxy-injected placeholder every other path uses. 0.38.0 closed one specific leak in this area — the session no longer exposes Desktop OAuth access tokens inside the sandbox — but the underlying warning still stands: expect Anthropic credentials to be present inside a Claude Desktop–connected sandbox, and don't treat that sandbox as isolated from your account the way a claude sandbox run without Desktop is.

Known bugs and their workarounds

Per-app connection notes

All four apps use the same shape: confirm ssh <name>.sbx works from a terminal first, then add the host inside the app's own remote/SSH UI — none of them discover sandboxes automatically from the wildcard config entry.

• VS Code and Cursor both use the Remote - SSH extension (Cursor inherits it from VS Code); run Remote-SSH: Connect to Host... and type the hostname. The first connection installs a server component inside the sandbox, so it's slower than every connection after.
• Claude Desktop: open the environment drop-down, choose + Add SSH connection, and enter the hostname as SSH Host. Leave SSH Port and Identity File blank — the managed config already supplies them, and filling them in yourself fights it. This is the app the credential warning above applies to; VS Code and Cursor sessions don't carry that warning because they don't inject Anthropic credentials.
• ChatGPT desktop: Settings > Connections, add an SSH connection manually with the sandbox hostname. Requires the sandbox to run a Codex template, since ChatGPT's remote server shells out to a codex binary.

Selecting the workspace

The remote folder picker in every app opens at the sandbox user's home directory (typically /home/agent), not the mounted project. A workspace keeps its absolute host path inside the sandbox — mount /Users/bob/src/my-project and that's the exact path to pick in the remote picker, not a path under /home/agent. This is the same property that lets claude --resume work across sandboxes in direct mode; it doesn't hold under --clone or on Windows, where host paths don't line up.

Port forwarding over the SSH connection

A remote-development client's local port forwarding works, but only reaches sandbox loopback addresses (localhost, 127.0.0.0/8, ::1) — traffic rides inside the SSH stream itself, not a published Docker port, so it doesn't need sbx ports. Where the forwarded listener binds on your host is the client's choice: bind to 127.0.0.1 and only your host can reach it; bind to a non-loopback address and other machines on your network can too, subject to your own firewall.

When the problem isn't the connection

Two failure modes look like an SSH setup problem but aren't:

• sbx rm or a stop hangs with an app connected — that's the session keeping the sandbox alive by design, not a bug. Disconnect the app, or pass --force.
• SSH (or any non-HTTP TCP) from inside the sandbox to an external host fails — for example git clone over git@host:... instead of HTTPS. That's the network policy denying the destination by default, not this integration layer; a hostname-based allow rule doesn't work for non-HTTP traffic; the fix is an IP:port rule. Route to diagnosing-sbx-sandboxes for that and for any credential-rejected-by-proxy symptom.

Last verified

Verified against the sbx docs of 2026-08-07 (re-fetched unchanged on 2026-08-10). SSH access to sandboxes is explicitly experimental — Docker shipped it in 0.37.0, tightened its credential-forwarding default in 0.37.1, and touched Claude Desktop's token handling again in 0.38.0 inside four months. Check sbx --version and the release notes before relying on any version-gated claim above.