开发工具包与 CLI 指南

应用集成优先使用 SDK。验证 HTTP 路由、鉴权 Header 或 SDK 行为时，可以使用原始 HTTP API。

层级	建议
浏览器或移动端	不要直接调用 Sandbox API，而是调用你的后端。
你的后端	持有 `SEACLOUD_API_KEY`，创建沙箱，保存 Sandbox ID，暴露产品级动作。
Agent runner	使用 SDK helper 操作命令/文件，并只把任务相关数据传入沙箱。
Sandbox runtime	只接收该工作负载需要的环境变量、源码文件和凭据。
支持 Dashboard	读取沙箱详情、日志、指标、使用限额和可观测性摘要。

安装

SDK	安装命令
Node	`npm install @seacloudai/sandbox`
Python	`pip install seacloud-sandbox`
Go	`go get github.com/SeaCloudAI/sandbox-go`

配置

export SEACLOUD_BASE_URL="https://sandbox-service.real-cloud.seaart.ai/api/v1/sandbox"
export SEACLOUD_API_KEY="YOUR_API_KEY"

变量	必填	用途
`SEACLOUD_BASE_URL`	是	API Base URL。
`SEACLOUD_API_KEY`	是	作为 `X-API-Key` 发送的 API Key。

SDK 能力速查

能力	Node	Python	Go
创建	`Sandbox.create(...)`	`Sandbox.create(...)`	`sandbox.Create(...)`
重连	`Sandbox.connect(...)`	`Sandbox.connect(...)`	`sandbox.Connect(...)`
文件	`sandbox.files`	`sandbox.files`	`sbx.Files()`
命令	`sandbox.commands`	`sandbox.commands`	`sbx.Commands()`
公网 URL	`sandbox.getHost(port)`	`sandbox.get_host(port)`	`sbx.GetHost(port)`
代码解释器	`sandbox.runCode(...)`	`sandbox.run_code(...)`	`RunCode`
模板构建	CLI / HTTP API	CLI / HTTP API	CLI / HTTP API

什么时候用 SDK 或 HTTP

任务	推荐方式
产品后端创建和操作沙箱	SDK
Agent 编排文件、命令和预览	SDK
列出并固定官方模板	SDK 或原始 HTTP
从本地源码构建自定义模板	CLI；后端集成可直接使用 HTTP API
调试路由契约或鉴权 Header	原始 HTTP
构建底层 Dashboard 或 Gateway 代理	原始 HTTP 加类型化响应模型
排查 SDK 行为	使用同一个 Sandbox ID 做原始 HTTP 复现

原始 HTTP 鉴权

SeaCloud Sandbox API 调用：

X-API-Key: <SEACLOUD_API_KEY>

调用 envdUrl 运行时接口：

X-Access-Token: <envdAccessToken>

运行时健康检查是例外：GET {envdUrl}/health、GET {envdUrl}/ 和 OPTIONS * 不需要运行时 Token。

Sandbox API 接口

Method	Path	说明
`POST`	`/sandboxes`	创建沙箱。
`GET`	`/sandboxes`	列出可见沙箱。
`GET`	`/sandboxes/:sandboxID`	查询详情。
`POST`	`/sandboxes/:sandboxID/connect`	重连运行时访问。
`POST`	`/sandboxes/:sandboxID/pause`	暂停运行时。
`POST`	`/sandboxes/:sandboxID/refreshes`	刷新 TTL。
`POST`	`/sandboxes/:sandboxID/timeout`	设置秒级超时。
`DELETE`	`/sandboxes/:sandboxID`	删除沙箱。
`GET`	`/usage/limits`	查询沙箱配额使用情况。
`GET`	`/observability/summary`	查询调用方用量、配额检查、接口可用性和建议动作。

建议保存的响应字段

保存不透明 ID 和公开状态字段。不要解析 ID，也不要从 ID 推导基础设施状态。

字段	是否保存	说明
`sandboxID`	是	查询详情、日志、指标、重连和删除的主键。
`templateID`	返回时保存	保存解析后的模板，便于审计和可复现。创建请求可省略该字段以使用 `base`。
`state` / `status`	是	展示当前生命周期状态。
`timeline`	可选	适合作为用户可见进度。
`diagnostic`	可选	适合排障文案和下一步建议。
`envdUrl`	短期使用	通过 SDK/runtime helper 使用，不要视为永久地址。
`envdAccessToken`	密钥	不要暴露给浏览器、用户或模型 Prompt。
`requestID`	错误时保存	用于支持工单和日志关联。

模板接口

Method	Path	说明
`GET`	`/api/v1/templates`	列出可见模板。
`GET`	`/api/v1/templates/resolve/:ref`	解析官方别名或标签。
`GET`	`/api/v1/templates/:id`	查询模板详情。

运行时 API 组

分组	路由
REST helpers	`GET /files`、`POST /files`、`POST /files/batch`、`POST /files/compose`、`POST /run`、`GET/POST /file`
Filesystem RPC	`POST /filesystem.Filesystem/*`
Process RPC	`POST /process.Process/*`

日志、指标与错误

表面	路由	说明
沙箱日志	`GET /sandboxes/:sandboxID/logs`	支持 cursor、direction、level、search，`limit` 最高 `1000`。
沙箱指标	`GET /sandboxes/:sandboxID/metrics`	Dashboard 指标快照。
批量指标	`GET /sandboxes/metrics`	查询可见沙箱的当前指标。
运行时指标	`GET {envdUrl}/metrics`	带 `X-Access-Token` 的直接运行时快照。

API 错误使用以下结构：

{
  "code": 400,
  "message": "timeoutMs is no longer supported in sandbox create requests; use timeout seconds",
  "requestID": "req-..."
}

遇到 429 时，读取 details.usageEndpoint，并向用户展示 scope、resource、metric、used、limit 和 remaining。

CLI 状态

CLI 速查

Sandbox 和 template 命令使用 SeaCloud 登录态：

seacloud auth login
seacloud auth status

核心沙箱流程：

seacloud sandbox create base --no-connect --wait --output json --metadata app=agent
seacloud sandbox list --state running,paused --output json
seacloud sandbox exec <sandbox_id> "python --version"
seacloud sandbox logs <sandbox_id> --limit 100 --direction backward --output json
seacloud sandbox metrics <sandbox_id> --output json
seacloud sandbox connect <sandbox_id> --shell bash
seacloud sandbox pause <sandbox_id>
seacloud sandbox timeout <sandbox_id> --seconds 3600
seacloud --dry-run sandbox kill <sandbox_id>
seacloud sandbox kill <sandbox_id>

网络与存储辅助命令：

seacloud sandbox network update <sandbox_id> --allow-internet-access=false --allow-out 1.1.1.1/32
seacloud sandbox volume create cache
seacloud sandbox create base --volume-mount cache:/cache --no-connect --wait --output json

事件、Webhook 与可观测性：

seacloud sandbox events --type sandbox.lifecycle.created --limit 20
seacloud sandbox webhook create --name lifecycle --url https://example.com/webhook --secret <secret> --event sandbox.lifecycle.created
seacloud sandbox webhook deliveries --status failed --limit 20
seacloud sandbox observability

模板项目与构建：

seacloud template init --language typescript --name my-template
seacloud template build my-template --dockerfile Dockerfile --tag v1
seacloud template list --format json
seacloud template get <template_id>
seacloud template logs <template> <build_id> --limit 100

完整命令列表见 SeaCloud CLI 命令速查。