| 说明 | 为智能体创建沙箱 |
| 用法 | sbx create AGENT|SANDBOX_KIT [PATH...] [flags] |
描述
创建一个沙箱，让智能体可以访问宿主机工作区。
第一个位置参数可以是内置智能体名称，也可以是沙箱 Kit 引用。沙箱 Kit 引用可以是本地目录、ZIP 文件、git 仓库或 OCI 引用。相对本地引用必须是明确的 路径，例如 ./my-kit 或 ../my-kit.zip。kit.shortcuts.<agent> 设置 （sbx settings set kit.shortcuts.claude myorg/claude:latest）会让该智能体名称 在本地沙箱中解析为所配置的 Kit 引用；云端 沙箱会忽略它。
省略路径即可创建不带工作区绑定挂载的沙箱：此时智能体 在容器自己的文件系统上工作，而不是在你的文件上。
创建完成后使用 "sbx run --name SANDBOX" 接入智能体。
可用智能体：claude、codex、copilot、cursor、devin、docker-agent、droid、kiro、 opencode、shell
使用 --cloud： 为智能体创建云端沙箱。
云端沙箱没有宿主机工作区，因此智能体后面不跟路径。规格大小 由 --cpus 和 --memory 决定，且必须落在可计费的规格上；不指定时 云端沙箱获得 2 个 CPU 和 4 GiB。用 -t / --template 指定的模板 必须已存在于云端镜像仓库中。
云端沙箱使用云端网络策略。宿主机网络和 HTTP 策略 不适用。用 "sbx --cloud policy init <allow-all|balanced|deny-all>" 设置云端账号默认值。
创建完成后使用 "sbx --cloud run <agent> --name SANDBOX" 接入智能体： 云端需要指定智能体，因为仅有名称不是唯一的句柄。
选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--allow-network | 允许云端沙箱出站的网络模式（仅云端；可以多次指定） | |
--clone | 让智能体在主机 Git 仓库的容器内私有克隆上运行（以只读方式挂载），而不是绑定挂载工作区；智能体的提交可以通过主机上的 sandbox-<name> git remote 访问 | |
--cpus | 0 | 分配给沙箱的 CPU 数量（0 = 自动：使用全部主机 CPU，Linux arm64 上最多 16 个） |
--deny-network | 在创建时为沙箱添加一条网络拒绝规则。可以多次指定。该规则仅适用于新建的沙箱，之后可以用 sbx policy ls <NAME> 列出，或用 sbx policy rm network --sandbox <NAME> --resource <HOST> 移除。在集中式治理下是安全的，因为本地拒绝规则只能收紧、绝不会放宽出站流量。 | |
-e, --env | 在沙箱中设置环境变量（可重复）：KEY=VALUE，或只写 KEY 以从当前环境取值 | |
--env-file | 从文件读取环境变量（可重复）。--env 的优先级高于任何文件；靠后的文件优先于靠前的文件 | |
--image-ref | 内联模式云端 create 使用的 OCI 镜像引用（与 --template 互斥；需要 --cpus 和 --memory） | |
--kit | 额外的 Kit 引用（必须是 Mixin；目录、ZIP、git 或 OCI）。可以多次指定 | |
--kit-arg | 为 Kit 声明的参数指定值，对所有 Kit 使用 name=value，对单个 Kit 使用 kit.name=value（可重复） | |
--kit-args-file | 包含 name=value 形式的 Kit 参数的文件，每行一个（可重复）；--kit-arg 的优先级更高 | |
-m, --memory | 内存上限，单位为二进制字节数（例如 512m、8g）。最小值：512 MiB。默认值：宿主机内存的 50%，并限制在 512 MiB–32 GiB 之间。最大值：宿主机内存。超过宿主机内存 75% 时会给出警告 | |
--mount | 把宿主机目录绑定挂载到 Kit 的 host-mount@1 路径（可重复传入）：HOST:SANDBOX_PATH。只能在创建新沙箱时使用。 | |
--name | 沙箱名称（默认：<agent>-<workdir>；2–63 个 ASCII 字母、数字、连字符或点；每个以点分隔的部分都必须以字母或数字开头和结尾；--cloud 不接受点；'default' 为保留名称） | |
--no-progress | 抑制进度输出 | |
--on-timeout | --ttl 到期时会发生什么：stop 就地停止沙箱，以便之后再次启动；restart 通过先停止再立即启动让沙箱保持运行；delete 则将其删除。不指定该标志时，服务端会在沙箱可以再次启动时停止它，否则将其删除。使用 restart 时，指定的 --ttl 必须至少为 1h（仅云端）。 | |
--platform | 目标平台：linux/amd64 或 linux/arm64（仅云端）。使用 --image-ref 时，省略该项可让服务端根据镜像解析平台，CLI 则把本地 CPU 作为多平台镜像的提示发送。使用 --template 时，省略该项表示沿用模板的平台。使用沙箱 Kit 时，Kit 的模板会针对该平台构建，并与其他平台分开缓存；省略该项则保留服务端的选择。 | |
-p, --publish | 把沙箱端口发布到主机（可重复）：[[HOST_IP:]HOST_PORT:]SANDBOX_PORT[/PROTOCOL] | |
--pull | 镜像拉取策略（always|missing|never；默认：保存的本地快照为 never，v3 Kit 组合为 missing，其他情况为 always） | |
--skills | 智能体技能目录（例如 ~/.claude/skills）的共享技能存储模式：off、readonly（以只读方式链接存储，目录仍可写）或 readwrite（把存储挂载到该目录之上，写入内容共享）。默认值：readonly，或已配置的 skills.defaultMode 设置。 | |
--static-mcp | 组成沙箱固定（静态）MCP 集合的 MCP 服务器名称。可以是逗号分隔的列表 （--static-mcp notion,atlassian）、重复的 flag（--static-mcp notion --static-mcp atlassian），或两者混合；所有写法都会累加到同一个集合中。使用 none 表示不包含 任何服务器的静态集合，仅适用于本地沙箱。该集合在创建时确定一次。本地沙箱使用 通过 'sbx mcp add' 注册的名称；云端沙箱在云端 MCP 网关上解析名称。 | |
-t, --template | 沙箱使用的容器镜像（默认：智能体专用镜像） | |
--ttl | 云端沙箱超时前的存活时间（TTL），例如 30m、2h、1h30m；单位不区分大小写；仅云端；默认值：由服务端决定 | |
-v, --volume | 挂载已有的持久卷，格式为 NAME:MOUNTPATH（仅云端，实验性；可重复） |
全局选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--cloud | 改为调用 Docker Cloud Sandboxes API，而不是本地 sandboxd（支持的动词正在逐步增加，运行 sbx --cloud --help 查看当前列表） | |
-D, --debug | 启用调试日志 | |
--no-input | 从不提示；需要应答的命令会直接失败，并给出应当运行的命令 |
示例
console
# 在当前目录中为 Claude 创建沙箱
sbx create claude .
# 创建带自定义名称的沙箱
sbx create --name my-project claude /path/to/project
# 创建时附加只读工作区
sbx create claude . /path/to/docs:ro
# 把额外的工作区挂载到沙箱内的指定路径
sbx create claude . /path/to/data:/workspace/data
# 创建不绑定工作区的沙箱
sbx create claude
# 从本地沙箱 Kit 创建
sbx create ../path/to/my-agent/
# 从本地目录或 ZIP 文件添加 Mixin
sbx create claude --kit ./my-mixin/
sbx create claude --kit ./my-mixin.zip
# 从 Docker Hub 添加 Mixin
sbx create claude --kit org/my-mixin:latest
# 从 OCI 引用添加 Mixin
sbx create claude --kit ghcr.io/org/my-mixin:latest
# 从 git 仓库添加 Mixin（git+https:// 或 git+ssh://，可选固定到某个 ref 和/或子目录）
sbx create claude --kit "git+https://github.com/org/repo.git#ref=v1.0&dir=mixins/foo"
# 在宿主机仓库的容器内克隆上运行智能体，并通过 git-daemon 连回去
sbx create --clone claude .
# 为 claude 创建云端沙箱
sbx --cloud create claude
# 创建内置 Mixin 的命名云端沙箱
sbx --cloud create --name my-project claude --kit ./my-mixin/
# 从云端镜像仓库中已存在的模板创建
sbx --cloud create -t TEMPLATE参见
sbx— 管理 AI 编程智能体沙箱。