参考
操作参考
查询全部公开的管理、运行时和可观测性操作。
本页仅列出公开语义目录。请在对应 CLI 上运行 help OPERATION，查看参数说明、默认值和经过验证的示例。
管理操作
命令前缀：sandbox-manager-cli
| 操作 | 参数 | 用途 | 手册 |
|---|---|---|---|
create_sandbox | --image IMAGE --workspace-bind-root PATH [--count N] | 创建一个或多个宿主机侧沙箱记录和运行时。 | CLI · MCP |
list_docker_images | 无 | 列出本地 Docker 镜像引用。 | CLI · MCP |
list_workspace_directories | [--path PATH] | 列出选择器可见的根目录或直接子目录。 | CLI · MCP |
destroy_sandbox | --sandbox-id ID | 停止守护进程、销毁运行时并移除记录。 | CLI · MCP |
list_sandboxes | 无 | 列出管理器已知的沙箱记录和生命周期状态。 | CLI · MCP |
inspect_sandbox | --sandbox-id ID | 检查一条沙箱记录和端点元数据。 | CLI · MCP |
squash_layerstacks | --sandbox-id ID | 压缩符合条件的层并重新挂载在线会话。 | CLI · MCP |
export_changes | --sandbox-id ID --dest PATH [--format dir|tar|tar-zst] | 应用或归档基础层以上的全部已发布层。 | CLI · MCP |
运行时命令操作
命令前缀：sandbox-runtime-cli --sandbox-id ID
| 操作 | 参数 | 用途 | 手册 |
|---|---|---|---|
exec_command | [--workspace-session-id ID] [--timeout-ms N] [--yield-time-ms N] COMMAND | 在现有或自动工作区会话中启动 shell 命令。 | CLI · MCP |
write_command_stdin | --command-session-id ID [--yield-time-ms N] TEXT | 向运行中命令的 stdin 追加文本。 | CLI · MCP |
read_command_lines | --command-session-id ID [--start-offset N] [--limit N] | 按稳定行偏移量读取已经渲染的输出。 | CLI · MCP |
运行时文件操作
命令前缀：sandbox-runtime-cli --sandbox-id ID
| 操作 | 参数 | 用途 | 手册 |
|---|---|---|---|
file_read | --path FILE [--offset N] [--limit N] [--workspace-session-id ID] | 从快照或在线会话读取 UTF-8 行。 | CLI · MCP |
file_write | --path FILE --content TEXT [--workspace-session-id ID] | 覆盖文件，并发布或保持会话私有。 | CLI · MCP |
file_edit | --path FILE --edits JSON [--workspace-session-id ID] | 按顺序执行精确字符串替换。 | CLI · MCP |
file_blame | --path FILE | 显示已发布文件的逐行归属。 | CLI · MCP |
可观测性操作
命令前缀：sandbox-observability-cli
| 操作 | 参数 | 用途 | 手册 |
|---|---|---|---|
snapshot | [--sandbox-id ID] | 读取一个在线快照，或聚合全部 ready 沙箱。 | CLI · MCP |
trace | --sandbox-id ID [--trace-id TRACE|last] | 把一条 trace 渲染为 span 瀑布图。 | CLI · MCP |
events | --sandbox-id ID [--name NAME] [--since-ms MS] [--last-n N] | 跨 trace 列出按新到旧排列的领域事件。 | CLI · MCP |
cgroup | --sandbox-id ID [--scope SCOPE] [--window-ms MS] | 读取沙箱资源或工作区磁盘时间序列。 | CLI · MCP |
layerstack | --sandbox-id ID [--workspace-id WS] [--window-ms MS] | 检查在线层租约、占用和趋势。 | CLI · MCP |
HTTP-only 例外
file_list 有意不放入 CLI 或 MCP 运行时目录。它只可通过守护进程 HTTP listener 的 POST /files/list，以及控制台代理的 POST /api/sandboxes/<id>/files/list 使用。可选 JSON 字段为 path、workspace_session_id 和 limit。
不公开的内部操作
工作区创建、捕获、拆除、重新挂载、层栈导出和导出分块读取属于内部协调路由，因此有意不在此列出。请改用 exec_command 自动会话和公开的 export_changes 管理操作。
经过认证的网关 RPC 与受限守护进程 HTTP allowlist 之间的区别，请参阅Web 控制台。