Skip to content
Open
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
43 changes: 30 additions & 13 deletions content/manuals/ai/sandboxes/integrations/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,8 @@ For example, if you mount `/Users/bob/src/my-project`, select

## How SSH connections work

### Managed SSH configuration

`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:
Expand All @@ -97,24 +99,18 @@ Host *.sbx
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.
You don't edit this block by hand. Its key entries work as follows:

`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.
- `Host *.sbx` maps sandbox hostnames to the sandbox daemon. Application host
pickers don't discover individual sandbox names from this wildcard, so enter
the hostname, such as `demo.sbx`, manually when you configure an integration.
- `User _default_user_` tells the daemon to use 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.
### Connection and authentication

Connections don't use a network port or an SSH key:

Expand All @@ -128,3 +124,24 @@ Connections don't use a network port or an SSH key:
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.

### Environment variables

SSH connections don't forward client environment variables into the sandbox.
The daemon acknowledges SSH environment requests for compatibility but ignores
their names and values.

### Port forwarding

SSH clients can use local port forwarding to make a service listening on the
sandbox's loopback interface available on the host. For example, a remote
development client can map `127.0.0.1:4321` in the sandbox to
`127.0.0.1:55565` on the host, choosing an available host port automatically.
Traffic passes through the SSH connection instead of a published Docker port.

The sandbox daemon accepts forwarded connections only to loopback addresses in
the sandbox, including `localhost`, `127.0.0.0/8`, and `::1`. The SSH client
chooses the bind address for the listener on the host. A listener bound to
`127.0.0.1` or `::1` is reachable only from the host. A client configured to
bind to a non-loopback address can make the forwarded service reachable from
other machines, subject to the host's network and firewall configuration.