这些集成使用本地沙箱的 SSH 访问。云沙箱使用不同的 SSH 配置和地址，请参阅 Connect with SSH。

你可以通过 SSH 把外部编辑器或桌面应用连接到正在运行的沙箱。这样你就能使用自己 已经熟悉的工具 —— VS Code、Cursor、Claude Desktop 等 —— 同时让代码在隔离的沙箱 中运行、构建和执行，而不是在你的宿主上。

每个沙箱都可以通过 <name>.sbx 访问，其中 <name> 是沙箱名称。SSH 设置好之后， <name>.sbx 的行为与其他 SSH 主机一样，因此任何支持通过 SSH 进行远程开发的工具 都可以连接它。

前置条件

• 已安装并登录 sbx CLI。请参阅 Get started。
• 一个 SSH 客户端。macOS 和大多数 Linux 发行版都自带 OpenSSH。在 Windows 上， 请安装 OpenSSH 客户端。
• 你想连接的编辑器或应用，并已安装其通过 SSH 进行远程开发的支持。

配置智能体凭据

在设置运行 AI 智能体的集成之前，先在 Docker Sandboxes 中为该智能体配置 model provider 凭据。通过 SSH 连接编辑器或桌面应用并不会把凭据提供给沙箱。你可以用 stored secrets 存储 API key，或完成 该智能体支持的 OAuth 登录流程。认证说明请参阅 agent pages。

启用 SSH 访问

运行一次 SSH 设置命令：

$ sbx setup ssh

该命令会在需要时启动 Docker Sandboxes daemon，并配置你的 SSH 客户端。你随时可以 重新运行它。

设置桌面应用连接

在 macOS 和 Windows 上，Docker Sandboxes 可以向 ChatGPT 和 Claude Desktop 添加 连接，在首次使用时创建专用沙箱。该工作流使用沙箱内的一个工作区。若要直接处理 已挂载的宿主项目，请创建沙箱并连接到它的主机名。

此设置需要 Docker Sandboxes v0.48.0 或更高版本。先把每个已安装的应用至少启动一次， 然后在运行下列命令前退出这些应用：

$ sbx setup ssh --auto-create

设置会向应用添加以下连接，并配置它们的 SSH 主机名。沙箱在首次使用连接时创建。

应用	连接名称	SSH 主机名	沙箱名称
ChatGPT	Docker Sandbox (Codex)	codex.sbx	ssh-codex
Claude Desktop	Docker Sandbox (Claude)	claude.sbx	ssh-claude

重新打开每个应用并选择它添加的连接。首次连接会创建对应的沙箱。之后的连接会复用 该沙箱及其文件；如果沙箱已停止，连接会将其启动。

这些沙箱没有挂载宿主工作区。在沙箱内克隆你的项目，并在应用的远程文件夹选择器中 选择它的目录。变更会留在沙箱内，直到你把它们推送到远程仓库或复制出来。

用 sbx rm 删除沙箱后，应用连接依然可用。下次连接会创建一个替代沙箱，但不会 恢复已删除的文件。

如果设置过程提示某个应用正在运行，请退出它并重新运行 sbx setup ssh。缺少 Docker 或智能体认证信息时，设置过程也会给出登录指引。

移除桌面应用连接

退出 ChatGPT 和 Claude Desktop，然后运行：

$ sbx setup ssh remove

这会移除托管的 SSH 配置和应用连接。已有的沙箱会保持原来的运行或停止状态。如果 不再需要它们，请另外用 sbx rm 删除沙箱。

创建或识别沙箱

要使用沙箱名称 <name>.sbx 连接，请先创建沙箱。ChatGPT 和 Claude Desktop 还 支持在首次连接时创建专用沙箱。要为当前目录创建 一个具名的 shell 沙箱：

$ sbx create --name demo shell .

要识别已有沙箱，请列出你的沙箱：

$ sbx ls

通过 SSH 连接到沙箱

使用沙箱名称加上 .sbx 后缀。例如，要连接名为 demo 的沙箱：

$ ssh demo.sbx

选择工作区文件夹

把应用连接到沙箱时选择的是远程环境，但它不一定自动打开主工作区。初始文件夹取决 于客户端。交互式 SSH shell 会从沙箱工作区启动，与 sbx exec 一致。编辑器的远程 文件夹选择器可能会打开沙箱用户的 home 目录 /home/agent。请在编辑器中明确选择 目标文件夹，而不要依赖其初始位置。

在远程文件夹选择器中，选择工作区在沙箱内的路径。从 /Users/bob/src/my-project 挂载的工作区默认使用同一个路径。自定义挂载目标（例如 /workspace/data）才是要在 编辑器中打开的路径。

Docker 提供的智能体模板为无挂载沙箱使用 /home/agent/workspace 作为工作区文件夹。

连接具体工具

• VS Code
• Cursor
• Claude Desktop
• ChatGPT
• T3 Code
• Orca

SSH 连接的工作方式

托管的 SSH 配置

sbx setup ssh 会向你的 SSH 配置写入一个托管块：在 macOS 和 Linux 上是 ~/.ssh/config，在 Windows 上是 %USERPROFILE%\.ssh\config。该块大致如下：

# >>> 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
# <<< docker sandboxes (managed) <<<

你不应手动编辑这个块。其关键条目含义如下：

• Host *.sbx 把沙箱主机名映射到沙箱 daemon。应用的 host 选择器无法从这个通配符 中发现各个沙箱名称，因此配置集成时请手动输入主机名，例如 demo.sbx。
• User _default_user_ 指示 daemon 使用沙箱镜像的默认用户，因此你的宿主用户名 永远不会被发送。

连接与认证

连接不使用网络端口，也不使用 SSH 密钥：

• ProxyCommand 通过 daemon 的本地 socket（macOS 和 Linux 上是 Unix domain socket，Windows 上是命名管道）转发 SSH 流。
• 只有在你保持有效的 Docker 登录状态时，daemon 才接受连接。认证绑定的是你的登录 状态，而不是存储的密钥。
• 每次连接都会校验 host key，因此 daemon 密钥轮换不会触发 host key 不匹配。

由于 SSH 在 daemon 处终止，沙箱内不会运行 SSH 服务器。对于普通的 <name>.sbx 连接，请先创建沙箱。桌面应用连接会在首次使用时 创建各自的专用沙箱。如果沙箱已停止，连接会自动启动它。

环境变量

SSH 连接不会把客户端环境变量转发进沙箱。为兼容性考虑，daemon 会确认 SSH 的环境 变量请求，但会忽略其中的名称和值。

端口转发

SSH 客户端可以使用本地端口转发，把监听在沙箱 loopback 接口上的服务暴露到宿主。 例如，远程开发客户端可以把沙箱内的 127.0.0.1:4321 映射到宿主上的 127.0.0.1:55565，并自动选择一个可用的宿主端口。流量经过 SSH 连接，而不是已发布 的 Docker 端口。

沙箱 daemon 只接受转发到沙箱内 loopback 地址的连接，包括 localhost、 127.0.0.0/8 和 ::1。监听器在宿主上绑定的地址由 SSH 客户端选择。绑定到 127.0.0.1 或 ::1 的监听器只能从宿主访问。配置为绑定非 loopback 地址的客户端 可以让转发的服务被其他机器访问，具体取决于宿主的网络和防火墙配置。