Docker Sandboxes

本页介绍本地沙箱、宿主服务和本地端口映射。关于云端端点，请参阅 Expose a port。

利用沙箱私有的运行时构建镜像、运行测试，并把本地工具连接到沙箱边界另一侧的开发 服务。

在沙箱内构建和测试 ​

智能体在沙箱内拥有 sudo 权限，因此可以安装软件包、启动数据库、运行测试依赖，并 准备好所需的环境。已安装的软件包在沙箱的生命周期内持续存在。需要重复使用时，用 Customize 把环境打包成模板或 kit。

智能体还可以构建 Docker 镜像、运行容器，并使用 Compose。所有这些都运行在沙箱私有的 Docker daemon 上，因此智能体启动的容器绝不会出现在你宿主的 docker ps 输出中。当你删除沙箱时， 其中的所有镜像、容器和卷都会随之删除。

这种模式很适合需要智能体运行项目测试套件或检查自己启动的服务的任务。如果你需要 从宿主访问该服务，请在创建沙箱时发布端口，或事后用 sbx ports 发布。

本地服务 ​

当沙箱中的智能体启动开发服务器，或智能体需要调用宿主上运行的服务时，使用这个 工作流。

访问沙箱内的服务 ​

沙箱是网络隔离的 —— 默认情况下，你的浏览器或本地工具 无法访问运行在其中的服务器。端口映射 8080:3000 会把沙箱端口 3000 发布到宿主 端口 8080。

如果你清楚需要哪些端口，创建沙箱时就发布它们：

console
$ sbx run --publish 8080:3000 --name my-sandbox claude

对于已有沙箱，用 sbx ports 从宿主转发流量。在已停止的 本地沙箱上发布端口会先启动它。

常见场景：智能体启动了一个开发服务器或 API，你想在浏览器中打开它，或针对它运行 测试。

console
$ sbx ports my-sandbox --publish 8080:3000
$ open http://localhost:8080

想让操作系统自行挑选一个空闲的宿主端口，而不是自己指定，只写沙箱端口即可。然后 用 sbx ports 查看分配到的宿主端口：

console
$ sbx ports my-sandbox --publish 3000
$ sbx ports my-sandbox

sbx ls 会在每个沙箱旁显示生效的端口映射，sbx ports 则会详细列出：

console
$ sbx ls
SANDBOX      AGENT    STATUS      PORTS                       WORKSPACE         CREATED
my-sandbox   claude   ● running   127.0.0.1:8080->3000/tcp4    /home/user/proj    2m

停止转发某个端口：

console
$ sbx ports my-sandbox --unpublish 8080:3000

要让某个服务可被访问，它必须在沙箱内监听所有接口，而不只是 127.0.0.1。IPv4 绑定 到 0.0.0.0，IPv4 和 IPv6 同时支持则绑定到 [::]。大多数开发服务器需要类似 --host 0.0.0.0 这样的标志来实现。

在宿主上，除非你指定其他协议，发布的端口默认绑定 IPv4（127.0.0.1），因此无论 解析器为 localhost 挑选哪个地址，http://localhost:<port>/ 都能访问监听在 IPv4 上的服务。指定显式的 IPv6 主机地址（例如 --publish [::1]:8080:3000）时，协议 默认变为 tcp6。要同时在两个地址族上发布，使用 --publish 8080:3000/tcp，只用 IPv6 则用 /tcp6。这两种方式都要求沙箱内的服务同时监听 IPv6 —— 把它绑定到 [::] —— 否则通过 ::1 到达的客户端会先被接受连接、随后连接被重置。

发布的端口在重启后依然有效：沙箱或 daemon 重启时，sbx 会重新发布它们。显式的 宿主端口会被复用，而以操作系统分配的宿主端口发布的端口（例如 --publish 3000） 每次启动都会得到不同的宿主端口。用 sbx ports my-sandbox 查明它。如果重启时显式的 宿主端口已被占用，CLI 或 dashboard 会提示你另选一个。删除沙箱会释放它的端口。

当 sbx run 重新连接到已有沙箱时，它会忽略 --publish。请用 sbx ports 在该沙箱 上发布端口。停止转发时，--unpublish 8080:3000 移除单个映射，--unpublish 3000 则移除映射到沙箱端口 3000 的所有宿主端口。

从沙箱访问宿主服务 ​

沙箱内可以用主机名 host.docker.internal 访问宿主上运行的服务。请用它代替 127.0.0.1 或你机器的本地网络 IP 地址，后两者在沙箱内无法访问。

沙箱代理在转发请求之前会把 host.docker.internal 转换成 localhost，因此你必须 把 localhost 加上具体端口加入 network policy 允许列表：

console
$ sbx policy allow network localhost:11434

然后在任何指向宿主服务的配置或请求中使用 host.docker.internal。例如，要从沙箱 shell 中验证连通性：

console
$ curl http://host.docker.internal:11434