Docker Sandboxes
说明创建（如需要）沙箱环境并接入
用法sbx env run [PATH...] [-- ARG...] [flags]

实验性

此命令为实验性功能。

实验性功能仅用于测试和反馈，其功能或设计可能在不同版本之间无预警地发生变化，也可能在未来的版本中被完全移除。

描述 ​

从 PATH（默认：当前目录）读取环境文件 并启动其中的智能体。如果沙箱已存在，会将其启动 并重新接入，而不重新置备；否则会先创建沙箱 （置备密钥和绑定），然后再接入。

每个 PATH 可以是目录（文件为 <PATH>/sbxenv.yaml），也可以是环境文件本身的路径。 传入多个 PATH 时会按顺序深度合并它们（与 docker-compose -f 的语义相同）： 后面的文件会覆盖前面的文件。 取值可以引用文件用 ${{ env.args.NAME }} 声明的参数，由 --env-arg 提供， 此外还有 ${{ env.projectDir }} 和 ${{ env.fileDir }}。 除此之外不会展开任何内容，因此 "$" 是字面文本。

可选的 entrypoint 和 cmd 数组只针对此环境覆盖智能体的启动方式。 省略或为 null 的字段继承默认值；空数组会清空 它们。后面的文件会替换这些数组，而不是与之拼接。配置了覆盖时， -- 之后的参数会替换 cmd；否则会转发给智能体保存的启动器。数组元素不会做 shell 展开。覆盖会绕过保存的启动器，在每次 env run 时生效，并保持 env exec、 普通的 sbx run、已发布的 Kit 以及沙箱的 PID 1 不变。分离运行的 只启动沙箱，不启动所配置的命令。继承启动默认值可能需要 重新解析该环境的工作负载 Kit。

目录形式的 PATH 选定 sbxenv.yaml；文件形式的 PATH 选定该文件。 不传 PATH 时，如果存在 ~/.sbxenv.yaml，则它提供共享默认值。 显式指定的 PATH 会跳过这些默认值。后面的文件会覆盖前面的值。 沙箱端口和生效协议都相同的端口、名称相同的 MCP 服务器，以及容器目标相同的 额外工作区，都以后出现的条目为准，同一文件内重复出现的条目也一样。 Kit 参数按来源合并。entrypoint 和 cmd 数组会替换之前的值；其他列表则拼接。

选项 ​

选项默认值说明
--clone覆盖 sbxenv.yaml 中的 workspace.clone（参见 'sbx create --clone'）
-d, --detach创建/启动沙箱但不接入
--env-arg为环境文件声明的参数设置值，格式为 name=value（可重复）
--env-args-file包含 name=value 形式环境参数的文件，每行一个（可重复）；--env-arg 的优先级更高
-f, --force不经询问直接应用环境计划
--kit-arg为 Kit 声明的参数设置值，name=value 表示所有 Kit，kit.name=value 表示某一个（可重复）；会覆盖 sbxenv.yaml 中 kits: 条目所固定的参数
--kit-args-file包含 name=value 形式 Kit 参数的文件，每行一个（可重复）；--kit-arg 的优先级更高
--name沙箱名称，会覆盖 sbxenv.yaml 中的 'name:' 以及推导出的 <agent>-<directory>（所有指向该环境的 'sbx env' 命令都需要使用同一个值）
--on-timeout--ttl 到期时会发生什么：'stop' 原地停止沙箱，以便之后重新启动；'restart' 通过先停止再立即启动来保持其运行；'delete' 则将其删除。不指定该标志时，服务端会在可以之后重新启动的情况下停止沙箱，否则将其删除。使用 'restart' 时，指定的 --ttl 必须至少为 1h（仅云端）。仅在创建沙箱时生效；接入已有沙箱时，'sbx --cloud env run' 会拒绝该标志。
--skip-host-commands跳过宿主机生命周期命令，并停用环境 MCP 命令，直到后续不带该标志的 env run
--ttl云端沙箱超时前的存活时间（TTL），例如 30m、2h、1h30m；单位不区分大小写；仅云端；默认：由服务端决定。仅在创建沙箱时生效；接入已有沙箱时，'sbx --cloud env run' 会拒绝该标志

全局选项 ​

选项默认值说明
--cloud改为调用 Docker Cloud Sandboxes API，而不是本地 sandboxd（支持的动词正在逐步增加，运行 sbx --cloud --help 查看当前列表）
-D, --debug启用调试日志
--no-input从不提示；需要应答的命令会直接失败，并给出应当运行的命令

示例 ​

console
sbx env run

# 启动但不接入
sbx env run --detach ./project

# 保留已配置的 entrypoint，只替换 cmd
sbx env run . -- --base HEAD

参见 ​

  • sbx env — （实验性）以声明式方式从 sbxenv.yaml 文件管理沙箱