diff --git a/content/manuals/ai/sandboxes/integrations/_index.md b/content/manuals/ai/sandboxes/integrations/_index.md index 77265d27193..11ff270af19 100644 --- a/content/manuals/ai/sandboxes/integrations/_index.md +++ b/content/manuals/ai/sandboxes/integrations/_index.md @@ -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: @@ -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: @@ -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 `.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.