| 说明 | 从 sbxenv.yaml 创建沙箱环境 |
| 用法 | sbx env create [PATH...] [flags] |
实验性
此命令为实验性功能。
实验性功能仅用于测试和反馈，其功能或设计可能在不同版本之间无预警地发生变化，也可能在未来的版本中被完全移除。
描述
从 PATH（默认：当前目录）读取环境文件，在沙箱范围内置备其中声明的密钥， 合并其凭据绑定，并创建沙箱。使用 "sbx env run" 接入。
每个 PATH 可以是目录（文件为 <PATH>/sbxenv.yaml），也可以是环境文件本身的路径。 传入多个 PATH 时会按顺序深度合并它们（与 docker-compose -f 的语义相同）： 后面的文件会覆盖前面的文件。 取值可以引用文件用 ${{ env.args.NAME }} 声明的参数，由 --env-arg 提供， 此外还有 ${{ env.projectDir }} 和 ${{ env.fileDir }}。 除此之外不会展开任何内容，因此 "$" 是字面文本。
目录形式的 PATH 选定 sbxenv.yaml；文件形式的 PATH 选定该文件。 不传 PATH 时，如果存在 ~/.sbxenv.yaml，则它提供共享默认值。 显式指定的 PATH 会跳过这些默认值。后面的文件会覆盖前面的值。 沙箱端口和生效协议都相同的端口、名称相同的 MCP 服务器，以及容器目标相同的 额外工作区，都以后出现的条目为准，同一文件内重复出现的条目也一样。 Kit 参数按来源合并。entrypoint 和 cmd 数组会替换之前的值；其他列表则拼接。
选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--clone | 覆盖 sbxenv.yaml 中的 workspace.clone（参见 'sbx create --clone'） | |
--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 create
# 不经询问直接批准计划
sbx env create --force ./project参见
sbx env— （实验性）以声明式方式从 sbxenv.yaml 文件管理沙箱