跳到正文
Ephemeral Sandbox mascot — a Siamese kitten peeking out of its wooden sandbox
浏览文档

接口

运行时 CLI 参考

通过运行时客户端执行命令、延续会话，以及读取或修改文件。

本页内容+

运行之前

每项运行时操作在发送前都需要全局 --sandbox-id ID 选择器。先用 sandbox-manager-cli list_sandboxes 查找 ID，再把选择器放在 clap 接受全局选项的任意位置。

Shell
sandbox-runtime-cli --sandbox-id ID help
sandbox-runtime-cli --sandbox-id ID help exec_command

命令文本和 stdin 是末尾位置参数。需要原样到达沙箱的 shell 元字符必须加引号。完整会话流程请参阅文件与命令。

按类别筛选操作

显示 7 / 7 项命令。

命令会话

启动命令、写入输入，并按稳定偏移量分页读取输出。

exec_command

启动沙箱 shell 命令

会话状态

在工作区会话中启动 shell 命令。省略 workspace_session_id 时使用自动的 publish_then_destroy 会话。

何时使用

  1. 仅在已有受管会话时使用 workspace_session_id。
  2. 若 status 为 running，请保留 command_session_id，供 read_command_lines 或 write_command_stdin 使用。
  3. 自动会话中的命令终止后，会先捕获并发布文件系统更改，再销毁会话。

语法

用法
sandbox-runtime-cli --sandbox-id ID exec_command [--workspace-session-id ID] [--timeout-ms N] [--yield-time-ms N] COMMAND

参数

参数类型必填说明
--sandbox-id ID (global)string是目标沙箱 ID（用于选择要查询的守护进程）。
--workspace-session-id IDstring否要在其中运行的现有工作区会话 ID。省略时创建 finalize 策略为 publish_then_destroy 的会话。
COMMANDstring是Shell 命令文本。
--timeout-ms Ninteger否命令超时时间，单位为毫秒。
--yield-time-ms Ninteger否首次等待输出的时间，单位为毫秒。

示例

Shell
sandbox-runtime-cli --sandbox-id ID exec_command pwd
sandbox-runtime-cli --sandbox-id ID exec_command --workspace-session-id ws-1 --yield-time-ms 0 "sleep 30"

代表性结果

JSON 输出
{
  "command_session_id": "namespace_execution_42",
  "workspace_session_id": "workspace_17",
  "status": "running",
  "exit_code": null,
  "wall_time_seconds": 0.25,
  "command_total_time_seconds": 0.25,
  "start_offset": 0,
  "end_offset": 2,
  "total_lines": 2,
  "original_token_count": 4,
  "output": "building…\n"
}

结果约定： status 为 running、ok、error、timed_out 或 cancelled；终态结果可能包含发布字段。

相关操作write_command_stdinread_command_lines

write_command_stdin

向正在运行的命令写入内容

会话状态

向运行中命令会话的 stdin 流追加文本，并返回有界的输出窗口。

何时使用

  1. 使用 exec_command 仍处于 running 状态时返回的 command_session_id。
  2. stdin 会原样写入；面向行的程序需要显式包含换行符。
  3. 结果沿用命令输出结构，写入后可能进入终态。

语法

用法
sandbox-runtime-cli --sandbox-id ID write_command_stdin --command-session-id ID [--yield-time-ms N] TEXT

参数

参数类型必填说明
--sandbox-id ID (global)string是目标沙箱 ID（用于选择要查询的守护进程）。
--command-session-id IDstring是exec_command 返回的命令会话 ID。
TEXTstring是要写入 stdin 的文本。
--yield-time-ms Ninteger否写入 stdin 后等待输出的时间。

示例

Shell
sandbox-runtime-cli --sandbox-id ID write_command_stdin --command-session-id cmd-1 hello

代表性结果

JSON 输出
{
  "command_session_id": "namespace_execution_42",
  "workspace_session_id": "workspace_17",
  "status": "ok",
  "exit_code": 0,
  "wall_time_seconds": 0.25,
  "command_total_time_seconds": 0.25,
  "start_offset": 0,
  "end_offset": 4,
  "total_lines": 4,
  "original_token_count": 4,
  "output": "accepted\ndone\n"
}

结果约定： 响应只包含有界的输出窗口。

相关操作exec_commandread_command_lines

read_command_lines

分页读取命令输出

只读

使用稳定的行偏移量读取命令会话已经渲染的输出。

何时使用

  1. 从偏移量 0 开始，随后从 end_offset 继续，直到它等于 total_lines。
  2. 命令可能仍在运行；status 和偏移量只是调用时刻的快照。
  3. 读取输出不会延长或触发工作区会话生命周期行为。

语法

用法
sandbox-runtime-cli --sandbox-id ID read_command_lines --command-session-id ID [--start-offset N] [--limit N]

参数

参数类型必填说明
--sandbox-id ID (global)string是目标沙箱 ID（用于选择要查询的守护进程）。
--command-session-id IDstring是exec_command 返回的命令会话 ID。
--start-offset Ninteger否；默认值 0开始读取的第一行偏移量，默认为 0。
--limit Ninteger否；默认值 200最多返回的输出行数，默认为 200，最大为 1000。

示例

Shell
sandbox-runtime-cli --sandbox-id ID read_command_lines --command-session-id cmd-1 --start-offset 0 --limit 100

代表性结果

JSON 输出
{
  "command_session_id": "namespace_execution_42",
  "workspace_session_id": "workspace_17",
  "status": "ok",
  "exit_code": 0,
  "wall_time_seconds": 0.25,
  "command_total_time_seconds": 0.25,
  "start_offset": 2,
  "end_offset": 4,
  "total_lines": 4,
  "original_token_count": 4,
  "output": "accepted\ndone\n"
}

结果约定： original_token_count 描述应用渲染边界前、未截断的源内容。

相关操作exec_commandwrite_command_stdin

文件与归因

读取快照、发布文件修改，并检查逐行归属。

file_read

读取 UTF-8 文本窗口

只读

从已发布快照或在线会话中，按仓库相对路径或工作区根目录绝对路径读取 UTF-8 文本窗口。

何时使用

  1. 省略 workspace_session_id 读取已发布快照；提供该值则读取尚未提交的会话内容。
  2. 当 truncated 为 true 时，沿 next_offset 继续分页读取长文件。
  3. 仅支持 UTF-8 普通文件。

语法

用法
sandbox-runtime-cli --sandbox-id ID file_read --path FILE [--offset N] [--limit N] [--workspace-session-id ID]

参数

参数类型必填说明
--sandbox-id ID (global)string是目标沙箱 ID（用于选择要查询的守护进程）。
--path FILEstring是要读取的仓库相对路径或工作区根目录绝对路径。
--offset Ninteger否；默认值 1开始读取的行号，从 1 计数，默认为 1。
--limit Ninteger否；默认值 2000最多读取的行数，默认为 2000，必须在 1..=2000 范围内。
--workspace-session-id IDstring否要在其中读取的现有工作区会话 ID。省略时读取快照。

示例

Shell
sandbox-runtime-cli --sandbox-id ID file_read --path README.md
sandbox-runtime-cli --sandbox-id ID file_read --path src/main.rs --offset 20 --limit 40

代表性结果

JSON 输出
{
  "path": "README.md",
  "content": "# Example\n\nProject overview…\n",
  "start_line": 1,
  "num_lines": 3,
  "total_lines": 3,
  "bytes_read": 31,
  "total_bytes": 31,
  "next_offset": null,
  "truncated": false
}

结果约定： 还有下一个窗口时，next_offset 不为 null。

相关操作file_writefile_editfile_blame

file_write

创建或覆盖文件

修改状态

在在线会话中把内容写入路径；未提供会话时，发布一个带归因的新层。

何时使用

  1. 仅在明确要覆盖整个目标文件时使用。
  2. 会话范围内的写入在会话解决前保持私有。
  3. 未提供会话时，运行时发布一个归属为 operation:<request_id> 的层。

语法

用法
sandbox-runtime-cli --sandbox-id ID file_write --path FILE --content TEXT [--workspace-session-id ID]

参数

参数类型必填说明
--sandbox-id ID (global)string是目标沙箱 ID（用于选择要查询的守护进程）。
--path FILEstring是要写入的仓库相对路径或工作区根目录绝对路径。
--content TEXTstring是要写入的文件内容。
--workspace-session-id IDstring否要在其中写入的现有工作区会话 ID。省略时发布一个层。

示例

Shell
sandbox-runtime-cli --sandbox-id ID file_write --path notes.txt --content 'hello'
sandbox-runtime-cli --sandbox-id ID file_write --path notes.txt --content 'hello' --workspace-session-id ws-1

代表性结果

JSON 输出
{
  "type": "update",
  "path": "notes.txt",
  "bytes_written": 12
}

结果约定： 新路径的 type 为 create；已有普通文件的 type 为 update。

相关操作file_readfile_editfile_blame

file_edit

按顺序应用精确替换

修改状态

在在线会话中按顺序执行精确字符串替换；未提供会话时，发布一个带归因的层。

何时使用

  1. 每项都需要 old_string 和 new_string；replace_all 默认为 false。
  2. 未启用 replace_all 时，old_string 必须恰好出现一次；空值、缺失、歧义和无变化编辑都会失败。
  3. 编辑按数组顺序执行；省略会话会立即发布一个持久层。

语法

用法
sandbox-runtime-cli --sandbox-id ID file_edit --path FILE --edits JSON [--workspace-session-id ID]

参数

参数类型必填说明
--sandbox-id ID (global)string是目标沙箱 ID（用于选择要查询的守护进程）。
--path FILEstring是要编辑的仓库相对路径或工作区根目录绝对路径。
--edits JSONarray是按顺序执行的 { old_string, new_string, replace_all? } JSON 数组。
--workspace-session-id IDstring否要在其中编辑的现有工作区会话 ID。省略时发布一个层。

示例

Shell
sandbox-runtime-cli --sandbox-id ID file_edit --path notes.txt --edits '[{"old_string":"a","new_string":"b"}]'
sandbox-runtime-cli --sandbox-id ID file_edit --path notes.txt --edits '[{"old_string":"a","new_string":"b","replace_all":true}]' --workspace-session-id ws-1

代表性结果

JSON 输出
{
  "type": "edit",
  "path": "notes.txt",
  "edits_applied": 1,
  "replacements": 2,
  "bytes_written": 26
}

结果约定： edits_applied 统计编辑对象数量；replacements 统计被替换的出现次数。

相关操作file_readfile_writefile_blame

file_blame

检查已发布内容的逐行归属

只读

根据最新审计事件，返回已发布路径中每一行的所有者。

何时使用

  1. 在命令、写入或编辑产生审计事件后使用。
  2. 范围从 1 开始，并完整覆盖最新的已知文件内容。
  3. 将 owner 字符串视为不透明值；没有审计记录时返回 not_found。

语法

用法
sandbox-runtime-cli --sandbox-id ID file_blame --path FILE

参数

参数类型必填说明
--sandbox-id ID (global)string是目标沙箱 ID（用于选择要查询的守护进程）。
--path FILEstring是要检查归因的仓库相对路径。

示例

Shell
sandbox-runtime-cli --sandbox-id ID file_blame --path README.md

代表性结果

JSON 输出
{
  "path": "notes.txt",
  "ranges": [
    {
      "start_line": 1,
      "line_count": 4,
      "owner": "original"
    },
    {
      "start_line": 5,
      "line_count": 2,
      "owner": "operation:request-id"
    }
  ]
}

结果约定： owner 可以是 workspace_session:<id>、operation:<id>、original 或 unknown。

相关操作file_readfile_writefile_edit

范围、请求 ID 与退出码

当其他系统需要稳定的请求标识时，请添加 --request-id VALUE。直接发布的文件修改归属于 operation:<request-id>；未提供时客户端会生成 ID。

Shell
sandbox-runtime-cli --sandbox-id ID --request-id change-42 file_write --path status.txt --content ready

退出码 0 向 stdout 写入成功 JSON；退出码 1 向 stderr 写入网关或操作错误；退出码 2 表示本地语法、校验或配置失败。命令自身的非零 exit_code 是成功操作响应中的数据，并非 CLI 进程退出码。

18 个结果