> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 使用沙箱

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

<Note>
  `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` 指定。
</Note>

## 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 对象形式提供的额外字段，合并进请求体。 | — |

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

```bash lines theme={null}
agentkit sandbox create --name dev-sandbox --type code --cpu 1000 --memory 2048
```

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

```bash lines theme={null}
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` |

```bash lines theme={null}
agentkit sandbox list --type code
```

## sandbox show

查看某个沙箱的详情。

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

```bash lines theme={null}
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 对象形式提供的额外字段，合并进请求体。 | — |

```bash lines theme={null}
agentkit sandbox update t-12345678 --description "开发沙箱" --port 9090
```

## sandbox delete

删除一个沙箱——即环境本身。若只需删除单个会话，请改用 [`sandbox rm`](#sandbox-rm)。

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

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

```bash lines theme={null}
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` |

```bash lines theme={null}
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` |

```bash lines theme={null}
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` |

```bash lines theme={null}
# 上传本地文件
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` |

```bash lines theme={null}
agentkit sandbox web --session my-session
```

## sandbox login

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

将本地的 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` |

```bash lines theme={null}
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` |

```bash lines theme={null}
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` |

```bash lines theme={null}
agentkit sandbox logs my-session --tail 100
```

## sandbox rm

停止并删除一个沙箱会话（或使用 `--all` 删除全部）。若要删除沙箱环境本身，请使用 [`sandbox delete`](#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` |

```bash lines theme={null}
agentkit sandbox rm my-session -y
```