生命周期、启停与重连

沙箱会经历创建、就绪、运行操作和清理阶段。所有运行时操作都应基于 create/connect 返回的 SDK 对象进行。

生命周期模型

create -> starting -> running -> pause/connect or refresh -> delete

动作	使用时机
`create`	分配运行时；不指定模板时默认使用 `base`。
`waitReady`	下一步立即需要文件、命令或端口能力。
`connect`	用已有 Sandbox ID 恢复运行时 URL/Token。
`pause`	停止运行资源，但保留元数据供后续重连。
`refresh`	为活跃任务延长 TTL。
`setTimeout`	修改秒级生命周期超时。
`delete`	永久清理一次性任务。

公开状态

API 响应只暴露少量公开状态。创建和清理过程中的中间阶段会在返回给公开客户端前折叠。

State/status	含义
`starting`	运行时正在创建，或等待健康心跳。
`running`	运行时 API 可用。
`paused`	Runtime 已停止，但持久元数据保留，可 connect/resume。
`deleted`	沙箱已移除。
`failed` / `error`	运行时未能变为可用，或生命周期操作失败。

沙箱创建、列表和详情响应可能包含 timeline 与 diagnostic。面向用户的进度和排障文案应优先使用这些字段，而不是解析日志文本。

就绪判断以运行时健康心跳为准。当 API 返回 running，或 SDK 的 waitReady 调用返回后，即可认为运行时 API 可用。

创建、详情和列表响应使用同一组公开字段语义。memoryMB 等资源字段、startedAt 等生命周期时间，以及 endAt 等过期时间应直接展示 API 返回值，不应替换为其他更新时间。

创建参数

参数	单位	说明
`templateID`	string	可选模板引用；不传或为空时使用 `base`。
`timeout`	秒	沙箱生命周期 TTL。
`waitReady`	boolean	等待运行时进入可用状态。
`envVars`	map	运行时环境变量覆盖。
`metadata`	map	用户侧元数据，便于搜索和调试。
`autoPause`	boolean	支持时可将超时动作映射为 pause 而不是 kill。
`autoResume`	boolean	支持时允许 router 访问暂停沙箱后触发自动恢复。
`network`	object	公网预览与出网策略，包括 `allowPublicTraffic`、`allowInternetAccess`、`allowOut` 和 `denyOut`。
`volumeMounts`	array	可选请求级挂载，仅支持 camelCase。

不要在创建/生命周期请求中发送已移除的兼容字段，例如 timeoutMs、secure、mcp 或 snake_case volume_mounts。这些字段会被拒绝，而不是静默忽略。沙箱生命周期 timeout 是秒；运行时命令 timeoutMs 仍然支持，单位是毫秒。

const sandbox = await Sandbox.create("base", {
  timeout: 1800,
  waitReady: true,
  envVars: { FOO: "bar" },
  metadata: { purpose: "demo" },
});

const sandboxId = sandbox.sandboxId;

await sandbox.connect({ timeout: 1800 });
// 或在另一个进程中：
const reconnected = await Sandbox.connect(sandboxId, { timeout: 1800 });

sandbox = Sandbox.create(
    "base",
    timeout=1800,
    waitReady=True,
    envVars={"FOO": "bar"},
    metadata={"purpose": "demo"},
)

sandbox_id = sandbox.sandbox_id
sandbox.connect(timeout=1800)
reconnected = Sandbox.connect(sandbox_id, timeout=1800)

超时与清理

Node
Python

await sandbox.setTimeout(3600);
await sandbox.refresh();
await sandbox.pause();
await sandbox.delete();

sandbox.set_timeout(3600)
sandbox.refresh()
sandbox.pause()
sandbox.delete()

原始 HTTP 接口

Method	Path	说明
`POST`	`/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 /sandboxes/:sandboxID`	状态、运行时访问字段、生命周期时间戳、`timeline` 和 `diagnostic`。
沙箱日志	`GET /sandboxes/:sandboxID/logs`	启动输出、就绪失败、应用日志和镜像拉取问题。
沙箱指标	`GET /sandboxes/:sandboxID/metrics`	当前 CPU、内存、磁盘、网络和任务计数。
可观测性摘要	`GET /observability/summary`	用户/项目用量、配额检查、接口可用性和建议动作。