| 说明 | 在沙箱中运行智能体 |
| 用法 | sbx run [flags] [AGENT|SANDBOX_KIT] [PATH...] [-- AGENT_ARGS...] |
描述
在沙箱中运行智能体；如果沙箱还不存在，会先创建。
第一个位置参数指定要运行的智能体，可以是内置智能体名称， 也可以是沙箱 Kit 引用。沙箱 Kit 引用可以是本地目录、 ZIP 文件、git 仓库或 OCI 引用。相对本地引用必须是 明确的路径，例如 ./my-kit 或 ../my-kit.zip；不带路径的值 仍保留智能体名称或沙箱名称的含义。kit.shortcuts.<agent> 设置（sbx settings set kit.shortcuts.claude myorg/claude:latest）会让该智能体名称 在本地沙箱中解析为所配置的 Kit 引用；云端 沙箱会忽略它。要按名称重新接入已有沙箱， 请使用 --name；当具名沙箱已存在时，智能体位置参数是可选的， 会从其 spec 中读取。
在 "--" 分隔符之后传入智能体参数。额外的工作区可以 以 PATH[:TARGET][:ro] 形式作为额外参数提供。TARGET 是 沙箱内的绝对路径；省略它则把 PATH 挂载到与宿主机相同的路径。追加 ":ro" 可把工作区以只读方式挂载；只读参数也可以指定单个文件， 这样在沙箱本可写入的工作区中，该路径将不可访问。
省略路径则挂载当前目录。传入路径则挂载其他工作区。
要创建沙箱但不接入，请改用 "sbx create"， 或传入 --detach (-d) 打印沙箱 ID 后退出，不打开 交互式会话。
可用智能体：claude、codex、copilot、cursor、devin、docker-agent、droid、kiro、 opencode、shell
使用 --cloud： 在云端沙箱中运行智能体；如果沙箱还不存在，会先创建。
第一个位置参数指定要运行的智能体：内置智能体 名称或沙箱 Kit 引用（本地目录、ZIP 文件、git 仓库 或 OCI 引用）。相对本地引用必须是明确的路径，例如 ./my-kit 或 ../my-kit.zip。云端沙箱没有宿主机工作区，因此智能体后面不跟路径。 在 "--" 分隔符之后传入智能体参数。
当要运行的智能体已有沙箱（正在运行或已停止）时，会提示你 选择一个复用，或创建一个新的。传入 --new 可跳过提示，始终 创建全新的沙箱。--name NAME 会在该名称的沙箱存在时复用并重启它， 否则创建它。通过沙箱 Kit 启动时始终创建全新沙箱，包含带构建内容的 Mixin 的 启动也一样。--detach 会跳过提示：与 --name 一起使用时， 该沙箱存在则重启它，否则创建一个新的。不带 --detach 的非交互式运行 会被拒绝，因此脚本需要传入 --detach（例如 sbx --cloud run -d claude && sbx --cloud exec ...）。
当位置参数指向已有沙箱时，不要传 --name。
使用 --cloud 时，--env 和 --env-file 只在创建沙箱时生效。 已有沙箱会保留原有环境；去掉这些 flag 以便重新接入， 或传入 --new 以使用新的取值创建沙箱。
规格大小由 --cpus 和 --memory 决定，且必须落在可计费的规格上；不指定时 云端沙箱获得 2 个 CPU 和 4 GiB。用 -t / --template 指定的模板 必须已存在于云端镜像仓库中；CLI 不会上传它。云端沙箱模型参见 https://docs.docker.com/ai/sandboxes/。
选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--allow-network | 允许云端沙箱出站访问的网络模式（仅限云端；可以多次指定） | |
--clone | 在容器内对主机 Git 仓库的私有克隆中运行智能体；必须在创建沙箱时设置（重新接入已有的 clone 模式沙箱时无效） | |
--cpus | 0 | 分配给沙箱的 CPU 数量（0 表示自动：使用全部主机 CPU，Linux arm64 上最多 16 个） |
--deny-network | 在创建时为该沙箱添加一条网络拒绝规则。可以多次指定。该规则仅对新建的沙箱生效，之后可以用 'sbx policy ls <NAME>' 列出，或用 'sbx policy rm network --sandbox <NAME> --resource <HOST>' 移除。在集中式治理下是安全的，因为本地拒绝规则只能收紧、绝不能放宽出站访问。 | |
-d, --detach | 启动沙箱并打印其 ID，但不打开智能体会话 | |
--detach-keys | 覆盖让会话保持运行的分离快捷键（Docker 风格，例如 "ctrl-\"、"ctrl-x,ctrl-d"）。默认：Ctrl-\. 当默认快捷键与智能体的键位冲突时使用（仅限云端）。 | |
-e, --env | 在沙箱中设置环境变量（可以重复指定）：KEY=VALUE，或只写 KEY 表示从当前环境取值。作用于智能体会话，重新接入时同样生效；如果本次运行创建了沙箱，也会把它固化到沙箱中 | |
--env-file | 从文件读取环境变量（可以重复指定）。--env 的优先级高于任何文件；后指定的文件优先于先指定的文件。作用于智能体会话，重新接入时同样生效；如果本次运行创建了沙箱，也会把它固化到沙箱中 | |
--image-ref | 内联模式云端创建所用的 OCI 镜像引用（与 --template 互斥；需要同时指定 --cpus 和 --memory） | |
--kit | 额外的 Kit 引用（必须是 Mixin；目录、ZIP、git 或 OCI）。可以多次指定 | |
--kit-arg | 为 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' 为保留名称） | |
--new | 始终创建新的云端沙箱，而不提示复用已有的沙箱（仅限云端） | |
--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]。在创建沙箱时生效；重新接入时忽略（请使用 "sbx ports"） | |
--pull | 镜像拉取策略（always|missing|never；默认：已保存的本地快照为 never，v3 Kit 组合为 missing，其余为 always） | |
--rm | 智能体会话退出后删除沙箱 | |
--skills | 智能体 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（仅限云端，实验性；可重复指定） | |
-w, --workdir | 启动智能体会话时所在的工作目录：可以是绝对路径，也可以相对于沙箱工作区。仅对本次会话生效，因此重新接入时同样有效 |
全局选项
| 选项 | 默认值 | 说明 |
|---|---|---|
--cloud | 改为调用 Docker Cloud Sandboxes API，而不是本地 sandboxd（支持的动词正在逐步增加，运行 sbx --cloud --help 查看当前列表） | |
-D, --debug | 启用调试日志 | |
--no-input | 从不提示；需要应答的命令会直接失败，并给出应当运行的命令 |
示例
# 在当前目录中用 claude 创建并运行沙箱
sbx run claude
# 从本地沙箱 Kit 创建并运行
sbx run ../path/to/my-agent/
# 从 OCI 沙箱 Kit 创建并运行
sbx run ghcr.io/foo/my-agent:latest
# 从本地目录或 ZIP 文件添加 Mixin
sbx run claude --kit ./my-mixin/
sbx run claude --kit ./my-mixin.zip
# 从 Docker Hub 添加 Mixin
sbx run claude --kit org/my-mixin:latest
# 从 OCI 引用添加 Mixin
sbx run claude --kit ghcr.io/org/my-mixin:latest
# 从 git 仓库添加 Mixin（git+https:// 或 git+ssh://，可选固定到某个 ref 和/或子目录）
sbx run claude --kit "git+https://github.com/org/repo.git#ref=v1.0&dir=mixins/foo"
# 创建并运行，附加额外的只读工作区
sbx run claude . /path/to/docs:ro
# 把额外的工作区挂载到沙箱内的指定路径
sbx run claude . /path/to/data:/workspace/data
# 按名称重新接入已有沙箱（智能体从其 spec 中读取）
sbx run --name existing-sandbox
# 按名称重新接入已有沙箱并校验预期的智能体
sbx run claude --name existing-sandbox
# 带智能体参数运行沙箱
sbx run claude -- --continue
# 在新的云端沙箱中运行 claude
sbx --cloud run claude
# 以非交互方式创建云端沙箱并打印其 ID
sbx --cloud run --detach claude
# 复用同名的云端沙箱，不存在时创建
sbx --cloud run --name my-project claude
# 带智能体参数运行
sbx --cloud run claude -- --continue参见
sbx— 管理 AI 编程智能体沙箱。