Sandboxes

生命周期接口用于创建隔离运行时、重连、暂停、延长 TTL 和删除沙箱。

创建沙箱

POST /sandboxes

请求体：

字段	类型	必填	说明
templateID	string	否	模板 ID 或官方类型，例如 base、code-interpreter、node、codex 或 api-server。为空时使用默认 base 模板。公开官方列表见模板指南。
timeout	integer	否	生命周期 TTL，单位秒。
waitReady	boolean	否	等待沙箱 ready 后再返回。
metadata	object	否	作为沙箱 label 持久化的键值元数据。
envVars	object	否	创建时注入的环境变量。
autoPause	boolean	否	超时后暂停，而不是直接 kill。
autoResume	boolean	否	允许 router 访问暂停沙箱时触发自动恢复。
allowInternetAccess	boolean	否	E2B 风格出网控制。
network.allowPublicTraffic	boolean	否	为 false 时，公网预览需要 traffic token。
network.allowInternetAccess	boolean	否	network 对象内的出网控制。
network.allowOut	string[]	否	IPv4/CIDR 出站 allowlist。
network.denyOut	string[]	否	IPv4/CIDR 出站 denylist。
volumeMounts	object[]	否	请求级卷挂载，每项为 { "name": "...", "path": "/..." }。

不要在创建请求中传 timeoutMs、secure、mcp 或 snake_case volume_mounts。timeout 单位是秒；运行时命令请求仍使用毫秒级 timeoutMs。

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

curl -sS -X POST "$SEACLOUD_API_BASE_URL/sandboxes" \
  -H "X-API-Key: $SEACLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "timeout": 1800,
    "waitReady": true,
    "metadata": { "app": "agent" }
  }'

响应：

{
  "templateID": "tpl-base-...",
  "sandboxID": "sandbox_...",
  "envdAccessToken": "<opaque-token>",
  "envdUrl": "https://sandbox-router.example/9000-sandbox_...",
  "status": "running",
  "state": "running",
  "startedAt": "2026-06-10T08:55:50Z",
  "activatedAt": "2026-06-10T08:55:50Z",
  "endAt": "2026-06-10T09:25:50Z",
  "timeline": []
}

列出沙箱

GET /sandboxes

常用查询参数：

Query	说明
state	生命周期状态过滤，可重复或逗号分隔。
metadata[key]	元数据过滤。
limit	分页大小。
nextToken	上一页返回的分页 token。

查询沙箱

GET /sandboxes/:sandboxID

返回详情、生命周期时间、运行时访问参数、timeline 和可选 diagnostic。

重连沙箱

POST /sandboxes/:sandboxID/connect

请求体：

{
  "timeout": 1800
}

请求体和 timeout 字段都是必需的。timeout=0 表示保持现有 TTL；正数表示从重连时间开始重置 TTL。该控制面接口会拒绝 timeoutMs。

暂停、续期、超时、删除

Method	Path	说明
POST	/sandboxes/:sandboxID/pause	暂停运行时并保留可恢复状态。
POST	/sandboxes/:sandboxID/refreshes	使用平台默认值或 duration 延长生命周期。
POST	/sandboxes/:sandboxID/timeout	使用 { "timeout": 3600 } 设置 TTL。
DELETE	/sandboxes/:sandboxID	删除沙箱。

POST /sandboxes/:sandboxID/timeout 同样要求 JSON body 中包含 timeout，并会拒绝 timeoutMs。

日志与指标

Method	Path	说明
GET	/sandboxes/:sandboxID/logs	日志查询，支持 limit、cursor、direction、level、search。
GET	/sandboxes/:sandboxID/metrics	单个沙箱最新指标。
GET	/sandboxes/metrics	批量指标。