Docker Sandboxes

这些连接说明使用的是本地沙箱。关于云端 SSH 设置，请参阅 Connect with SSH。

T3 Code 的 SSH 集成让桌面应用可以在沙箱内驱动编程智能体。T3 Code 没有专用的 Docker Sandboxes 集成 —— 它把沙箱当作普通的 SSH 主机，连接过去，并在其中启动一个 回连到应用的 T3 server。

前置条件 ​

首次连接会在沙箱内安装 T3 server。t3 为 Linux 提供预编译的原生模块，因此不需要 编译，但这些二进制文件链接了 libatomic1。Docker 提供的模板已包含它。

t3code kit更进一步： 它在沙箱创建时安装 t3 npm 包，并在基础镜像缺少 libatomic1 时一并安装，这样 首次连接时 server 已经就绪。它可以搭配任何基础镜像自带 Node.js 18 或更高版本的 智能体使用，所有标准智能体模板都满足这一条件：

console
$ sbx run claude --kit docker.io/sbx/t3code-kit:latest

用自定义 base image 构建且不含 libatomic1 的沙箱，需要在首次连接前安装它，除非你应用上面的 kit —— 它会替你 安装：

console
$ sbx exec <sandbox> -- sudo apt-get update
$ sbx exec <sandbox> -- sudo DEBIAN_FRONTEND=noninteractive apt-get install -y libatomic1

确认它已就位：

console
$ sbx exec <sandbox> -- sh -lc 'ldconfig -p | grep libatomic.so.1'

连接 ​

确认你可以通过终端连接到该沙箱：

console
$ ssh demo.sbx

在 T3 Code 中添加一个 SSH environment，并把沙箱主机名（例如 demo.sbx）填入 host。首次连接会在沙箱内安装 T3 server —— 除非 t3code kit 已经预装好 —— 因此 需要一点时间。之后的连接会快很多。

然后添加一个新项目，从列表中选择该 SSH environment，并把 已挂载的工作区选为沙箱内的项目目录。

排查 server 一直无法就绪的问题 ​

T3 Code 可能连接失败并报出类似下面的错误（此处为便于阅读做了折行处理）。它把连接 失败和沙箱内 npm 的安装输出拼接在一起，显示在同一个错误对话框中：

text
Could not prepare the SSH environment: ... SshCommandError: Connecting to
sandbox "sandboxes"… Remote T3 server did not become ready on
127.0.0.1:3773. npm WARN EBADENGINE Unsupported engine { package:
'ini@7.0.0', required: { node: '^22.22.2 || ^24.15.0 || >=26.0.0' },
current: { node: 'v22.22.1', npm: '9.2.0' } }

npm WARN EBADENGINE 相关的行是在警告传递依赖 ini 的问题，与失败本身无关： 只有设置了 engine-strict 时 npm 才会强制执行引擎版本要求，而该设置默认关闭， 因此仅凭这条警告，安装仍会继续。

最常见的原因是缺少共享库和磁盘空间耗尽。手动安装 t3 并运行它，可以把两者区分 开来：

console
$ sbx exec <sandbox> -- sh -lc \
  'rm -rf /tmp/t3probe && mkdir -p /tmp/t3probe && cd /tmp/t3probe \
   && npm init -y >/dev/null && npm install t3@latest 2>&1 | tail -20 \
   && ./node_modules/.bin/t3 --version'

缺少 libatomic1 时，安装会成功完成，但留下一个无法启动的二进制文件：

text
node_modules/@t3code/t3-linux-x64/t3: error while loading shared libraries:
libatomic.so.1: cannot open shared object file: No such file or directory

请按 Prerequisites 中的说明安装它。

磁盘空间耗尽会让安装本身以 ENOSPC 失败：

text
npm ERR! code ENOSPC
npm ERR! nospc ENOSPC: no space left on device

检查可用磁盘空间：

console
$ sbx exec <sandbox> -- df -h /

一个沙箱可能同时存在这两个问题。修复其中一个后，仍会看到同样的顶层错误，因此 在断定沙箱已就绪之前，请同时检查共享库和磁盘空间。按需释放空间或安装 libatomic1，然后重新连接。

排查 turn/setPermissionMode failed 错误 ​

如果你的组织用策略文件管理 Claude Code，本地的 T3 Code 会话可能会因 turn/setPermissionMode failed 而无法启动。T3 Code 的默认运行模式是 Full access， 它对应 Claude Agent SDK 的 bypassPermissions 模式。禁用该模式的托管策略会拒绝 这个请求。

在 macOS 上，检查这是否会影响你：

console
$ cat "/Library/Application Support/ClaudeCode/managed-settings.json"

如果 permissions.disableBypassPermissionsMode 被设置为 disable，请把 T3 Code 切换到其他运行模式，例如 Supervised、Auto-accept edits 或 Auto，然后启动新的 会话。权限模式在会话启动时捕获一次，因此在一个已经失败的会话中切换模式无法 恢复它。

此限制针对运行 Claude Code 的宿主，而不是沙箱。连接到沙箱的会话不受宿主托管策略 约束，因此在那里 Full access 可以正常工作。