| 说明 | 在沙箱环境中执行命令 |
| 用法 | sbx env exec [flags] [PATH...] -- COMMAND [ARG...] |
实验性
此命令为实验性功能。
实验性功能仅用于测试和反馈，其功能或设计可能在不同版本之间无预警地发生变化，也可能在未来的版本中被完全移除。
描述
在 sbxenv.yaml 声明的沙箱中运行 COMMAND。若沙箱 已停止，会先将其启动。如果沙箱不存在，交互式终端会提示 你创建它并批准环境计划，然后才运行 COMMAND。没有交互式 终端，或使用 --no-input 时，请先用 "sbx env create" 创建它。
-- 之前的参数是环境文件路径，遵循与其他 "sbx env" 子命令相同的 规则：每个 PATH 可以是目录（文件为 <PATH>/sbxenv.yaml），也可以是环境文件本身的 路径，传入多个则按顺序深度合并。不带 -- 时，每个位置参数都构成命令， 环境文件从当前目录读取。
目录形式的 PATH 选定 sbxenv.yaml；文件形式的 PATH 选定该文件。 不传 PATH 时，如果存在 ~/.sbxenv.yaml，则它提供共享默认值。 显式指定的 PATH 会跳过这些默认值。后面的文件会覆盖前面的值。 沙箱端口和生效协议都相同的端口、名称相同的 MCP 服务器，以及容器目标相同的 额外工作区，都以后出现的条目为准，同一文件内重复出现的条目也一样。 Kit 参数按来源合并。entrypoint 和 cmd 数组会替换之前的值；其他列表则拼接。
Flag 的行为与 "sbx exec" 相同。
退出状态即命令的退出状态。如果 sbx 无法运行该命令（例如沙箱不存在），则以 125 退出。命令不存在时以 127 退出；但如果云端后端把它报告为错误而非状态码，则以 125 退出。
选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--detach-keys | 覆盖用于分离交互式云端 exec 会话的按键组合（本地 exec 不支持） | |
-e, --env | 设置环境变量 | |
--env-arg | 为环境文件声明的参数设置值，格式为 name=value（可重复） | |
--env-args-file | 包含 name=value 形式环境参数的文件，每行一个（可重复）；--env-arg 的优先级更高 | |
--env-file | 读入环境变量文件 | |
-i, --interactive | 即使未接入也保持 STDIN 打开 | |
--name | 沙箱名称，会覆盖 sbxenv.yaml 中的 'name:' 以及推导出的 <agent>-<directory>（所有指向该环境的 'sbx env' 命令都需要使用同一个值） | |
-t, --tty | 分配一个伪 TTY | |
-u, --user | 用户名或 UID（格式：<name|uid>[:<group|gid>]） | |
-w, --workdir | 容器内的工作目录 |
全局选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--cloud | 改为调用 Docker Cloud Sandboxes API，而不是本地 sandboxd（支持的动词正在逐步增加，运行 sbx --cloud --help 查看当前列表） | |
-D, --debug | 启用调试日志 | |
--no-input | 从不提示；需要应答的命令会直接失败，并给出应当运行的命令 |
示例
console
# 在当前目录声明的环境中运行命令
sbx env exec go test ./...
# 打开一个 shell
sbx env exec -it -- bash
# 使用显式合并的环境文件运行
sbx env exec sbxenv.yaml override.yaml -- npm test参见
sbx env— （实验性）以声明式方式从 sbxenv.yaml 文件管理沙箱