使用沙箱

沙箱是一个隔离的 code 或 skill 环境。sandbox 命令组既管理沙箱的完整生命周期——创建、列出、查看、更新、删除——也提供对沙箱的操作：在会话中运行命令、打开交互式终端、传输文件、预览 Web、注入订阅凭据，以及管理会话。

run、shell、cp、web 和 login 共有一组会话与沙箱相关标志：-s, --session <id>（会话 ID，存在则复用，否则新建）、--tool-id <id>（沙箱 ID）、--type <type>（沙箱类型 code | skill，默认 code）、--auto-create（始终新建一个沙箱，即使项目内已有）、-r, --region <region>（Volcengine 区域）、-p, --project <name>（AgentKit 项目，默认 default）。sessions、logs 和 rm 只接受其中适用于沙箱解析的部分标志，具体以各命令的参数表为准。attach 是 shell 的别名。未传 --tool-id 且未加 --auto-create 时，CLI 会在项目内查找该类型的沙箱：恰好一个时自动选用；存在多个时命令会失败并要求显式传入 --tool-id；一个都没有时需加 --auto-create。加上 --auto-create 则始终新建一个全新沙箱——即使项目内已有——并等待其就绪后再使用。项目内已有多个 code 沙箱属常见情况，此时可用 agentkit sandbox list 查到目标 ID 后通过 --tool-id 指定。

sandbox create

创建一个沙箱（code 或 skill 环境）。

标志/参数	说明	默认值
`--name <name>`	沙箱名称（必填）。	—
`--type <type>`	沙箱类型：`code` \| `skill`。	`code`
`-r, --region <region>`	Volcengine 区域。	取自环境
`--description <text>`	描述。	—
`--command <command>`	容器启动命令。	—
`--image-url <url>`	容器镜像地址。	—
`--port <port>`	容器端口。	—
`-p, --project <name>`	项目名。	`default`
`--role-name <role>`	IAM 角色名。	—
`--apmplus`	启用 APMPlus。	—
`--cpu <milli>`	CPU（毫核）。	—
`--memory <mb>`	内存（MB）。	—
`--enable-security`	启用安全沙箱。	—
`--enable-tos`	将 TOS 挂载进沙箱。	—
`--env <KEY=VALUE>`	环境变量（可重复）。	—
`--json <jsonString>`	以 JSON 对象形式提供的额外字段，合并进请求体。	—

sandbox create 会在云端创建计算资源，资源存续期间可能产生费用。创建前确认项目、地域、规格与镜像来源；不再使用时，通过 sandbox delete 删除沙箱。

agentkit sandbox create --name dev-sandbox --type code --cpu 1000 --memory 2048

以下示例使用自定义镜像创建一个 Web 沙箱。请将镜像地址替换为项目能够访问的镜像：

agentkit sandbox create \
  --name web-sandbox \
  --image-url your-registry.example.com/team/python-web:latest \
  --command "python -m http.server 8080" \
  --port 8080

sandbox list

列出项目内的沙箱（code 与 skill 环境）。

标志/参数	说明	默认值
`-r, --region <region>`	Volcengine 区域。	自动探测
`-p, --project <name>`	项目名。	`default`
`--type <type>`	按沙箱类型过滤：`code` \| `skill`。	—
`--json`	输出原始 JSON。	`false`

agentkit sandbox list --type code

sandbox show

查看某个沙箱的详情。

标志/参数	说明	默认值
`<id>`	沙箱 ID，如 `t-xxxxxxxx`（必填）。	—
`-r, --region <region>`	Volcengine 区域。	自动探测
`--json`	输出原始 JSON。	`false`

agentkit sandbox show t-12345678

sandbox update

更新某个沙箱的配置。

标志/参数	说明	默认值
`<id>`	沙箱 ID，如 `t-xxxxxxxx`（必填）。	—
`-r, --region <region>`	Volcengine 区域。	自动探测
`--description <text>`	描述。	—
`--command <command>`	容器启动命令。	—
`--image-url <url>`	容器镜像地址。	—
`--port <port>`	容器端口。	—
`--apmplus`	启用 APMPlus。	—
`--json <jsonString>`	以 JSON 对象形式提供的额外字段，合并进请求体。	—

agentkit sandbox update t-12345678 --description "开发沙箱" --port 9090

sandbox delete

删除一个沙箱——即环境本身。若只需删除单个会话，请改用 sandbox rm。

删除沙箱不可恢复，沙箱中的会话以及未另行保存的文件可能同时丢失。执行前确认沙箱 ID，并把需要保留的文件下载到本地或持久化存储。

标志/参数	说明	默认值
`<id>`	沙箱 ID，如 `t-xxxxxxxx`（必填）。	—
`-r, --region <region>`	Volcengine 区域。	自动探测
`-y, --yes`	跳过确认提示。	`false`

agentkit sandbox delete t-12345678 --yes

sandbox run

在沙箱会话中运行命令并打印其输出。

标志/参数	说明	默认值
`<command>`	要运行的命令（必填）	无
`--json`	打印原始结果（`{ output, ... }`）	`false`
`--cwd <dir>`	运行时的工作目录	无
`--model-name <name>`	沙箱编码智能体所用的模型	无
`--model-api-key <key>`	模型 API key	无
`--model-provider <provider>`	模型提供方	无
`--cpu <milli>`	`--auto-create` 时的 CPU（毫核）	无
`--memory <mb>`	`--auto-create` 时的内存（MB）	无
`--timeout <seconds>`	命令中止前的最长等待秒数；`0` 表示不限制	`30`
`-s, --session <id>`	会话 ID（存在则复用，否则生成）	无
`--tool-id <id>`	沙箱 ID。省略时自动解析：项目内该类型沙箱唯一则自动选用，存在多个时必须指定，一个都没有时需配合 `--auto-create`	自动解析
`--type <type>`	沙箱类型：`code` \| `skill`	`code`
`--auto-create`	始终新建一个沙箱，即使项目内已有	`false`
`-r, --region <region>`	Volcengine 区域	无
`-p, --project <name>`	AgentKit 项目	`default`

agentkit sandbox run "ls -la" --session my-session

一次性的 run 会等待命令执行结束，因此交互式程序——编辑器、REPL，或不带参数直接运行的 codex——会一直阻塞直至超时。交互场景请改用 agentkit sandbox shell；对确需长时间运行的非交互任务，可调大 --timeout 或将其设为 0。

sandbox shell

在沙箱会话中打开交互式终端（按 Ctrl-] 脱离）。sandbox attach 是此命令的别名。

标志/参数	说明	默认值
`--tmux`	附加或创建一个持久化 tmux 会话	`false`
`--command <cmd>`	附加后先执行的初始命令	无
`--workspace <dir>`	沙箱工作区根目录	无
`--src-dir <path>`	附加前要上传的本地文件/目录	无
`--dst-dir <dir>`	`--src-dir` 的远端目标目录（位于 `--workspace` 下）	无
`--model-name <name>`	沙箱编码智能体所用的模型	无
`--model-api-key <key>`	模型 API key	无
`--model-provider <provider>`	模型提供方	无
`-s, --session <id>`	会话 ID（存在则复用，否则生成）	无
`--tool-id <id>`	沙箱 ID。省略时自动解析：项目内该类型沙箱唯一则自动选用，存在多个时必须指定，一个都没有时需配合 `--auto-create`	自动解析
`--type <type>`	沙箱类型：`code` \| `skill`	`code`
`--auto-create`	始终新建一个沙箱，即使项目内已有	`false`
`-r, --region <region>`	Volcengine 区域	无
`-p, --project <name>`	AgentKit 项目	`default`

agentkit sandbox shell --tmux --session my-session

sandbox cp

在本地与沙箱会话之间复制文件，用 : 前缀标记远端一侧。

标志/参数	说明	默认值
`<src>`	源路径（远端一侧以 `:` 前缀，必填）	无
`<dst>`	目标路径（远端一侧以 `:` 前缀，必填）	无
`--overwrite`	下载时覆盖已存在的本地文件	`false`
`-s, --session <id>`	会话 ID（存在则复用，否则生成）	无
`--tool-id <id>`	沙箱 ID。省略时自动解析：项目内该类型沙箱唯一则自动选用，存在多个时必须指定，一个都没有时需配合 `--auto-create`	自动解析
`--type <type>`	沙箱类型：`code` \| `skill`	`code`
`--auto-create`	始终新建一个沙箱，即使项目内已有	`false`
`-r, --region <region>`	Volcengine 区域	无
`-p, --project <name>`	AgentKit 项目	`default`

# 上传本地文件
agentkit sandbox cp ./local.txt :/workspace/local.txt --session my-session

# 下载远端文件
agentkit sandbox cp :/workspace/report.json ./report.json --session my-session

# 目标文件已存在时允许覆盖
agentkit sandbox cp :/workspace/report.json ./report.json --session my-session --overwrite

sandbox web

在浏览器中打开沙箱的 Web 预览。

标志/参数	说明	默认值
`--no-open`	仅打印 URL，不打开浏览器	`false`
`-s, --session <id>`	会话 ID（存在则复用，否则生成）	无
`--tool-id <id>`	沙箱 ID。省略时自动解析：项目内该类型沙箱唯一则自动选用，存在多个时必须指定，一个都没有时需配合 `--auto-create`	自动解析
`--type <type>`	沙箱类型：`code` \| `skill`	`code`
`--auto-create`	始终新建一个沙箱，即使项目内已有	`false`
`-r, --region <region>`	Volcengine 区域	无
`-p, --project <name>`	AgentKit 项目	`default`

agentkit sandbox web --session my-session

此命令会将本地订阅凭据复制到远端沙箱会话。仅在受信任的沙箱和专用会话中使用，避免向他人共享该会话；使用完成后，通过 agentkit sandbox rm <session> -y 删除会话。

将本地的 codex/claude 订阅凭据注入到沙箱会话中。

标志/参数	说明	默认值
`--provider <provider>`	`codex` \| `claude`	`codex`
`--auth-file <path>`	使用指定的本地凭据文件	无
`--codex-home <dir>`	本地 codex home	`$CODEX_HOME` 或 `~/.codex`
`-s, --session <id>`	会话 ID（存在则复用，否则生成）	无
`--tool-id <id>`	沙箱 ID。省略时自动解析：项目内该类型沙箱唯一则自动选用，存在多个时必须指定，一个都没有时需配合 `--auto-create`	自动解析
`--type <type>`	沙箱类型：`code` \| `skill`	`code`
`--auto-create`	始终新建一个沙箱，即使项目内已有	`false`
`-r, --region <region>`	Volcengine 区域	无
`-p, --project <name>`	AgentKit 项目	`default`

agentkit sandbox login --provider claude --session my-session

sandbox sessions

列出活跃的沙箱会话。

标志/参数	说明	默认值
`--tool-id <id>`	沙箱 ID。省略时自动解析：项目内该类型沙箱唯一则自动选用，存在多个时必须指定，一个都没有时需配合 `--auto-create`	自动解析
`--type <type>`	沙箱类型：`code` \| `skill`	`code`
`-r, --region <region>`	Volcengine 区域	无
`-p, --project <name>`	AgentKit 项目	`default`
`--json`	输出原始 JSON	`false`

agentkit sandbox sessions

sandbox logs

显示某个沙箱会话的日志。

标志/参数	说明	默认值
`[session]`	会话 ID	无
`--tool-id <id>`	沙箱 ID。省略时自动解析：项目内该类型沙箱唯一则自动选用，存在多个时必须指定，一个都没有时需配合 `--auto-create`	自动解析
`--type <type>`	沙箱类型：`code` \| `skill`	`code`
`--tail <n>`	最大日志行数	无
`-r, --region <region>`	Volcengine 区域	无
`-p, --project <name>`	AgentKit 项目	`default`
`--json`	输出原始 JSON	`false`

agentkit sandbox logs my-session --tail 100

sandbox rm

停止并删除一个沙箱会话（或使用 --all 删除全部）。若要删除沙箱环境本身，请使用 sandbox delete。

标志/参数	说明	默认值
`[session]`	会话 ID	无
`--tool-id <id>`	沙箱 ID。省略时自动解析：项目内该类型沙箱唯一则自动选用，存在多个时必须指定，一个都没有时需配合 `--auto-create`	自动解析
`--type <type>`	沙箱类型：`code` \| `skill`	`code`
`--all`	删除该沙箱上的所有会话	`false`
`-y, --yes`	跳过确认	`false`
`-r, --region <region>`	Volcengine 区域	无
`-p, --project <name>`	AgentKit 项目	`default`

agentkit sandbox rm my-session -y

开始使用

AI-Friendly

命令参考

sandbox create

sandbox list

sandbox show

sandbox update

sandbox delete

sandbox run

sandbox shell

sandbox cp

sandbox web

sandbox sessions

sandbox logs

sandbox rm

​sandbox create

​sandbox list

​sandbox show

​sandbox update

​sandbox delete

​sandbox run

​sandbox shell

​sandbox cp

​sandbox web

​sandbox login

​sandbox sessions

​sandbox logs

​sandbox rm

sandbox create

sandbox list

sandbox show

sandbox update

sandbox delete

sandbox run

sandbox shell

sandbox cp

sandbox web

sandbox login

sandbox sessions

sandbox logs

sandbox rm