生命周期、启停与重连

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

生命周期模型

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

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

公开状态

API 响应只暴露产品安全状态。Atlas 内部的 new、warming、warm、creating、active、stopped、destroying 等状态会在返回给公开客户端前折叠。

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

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

创建参数

参数	单位	说明
`templateID`	string	必填模板引用。
`timeout`	秒	沙箱生命周期 TTL。
`waitReady`	boolean	等待运行时进入可用状态。
`envVars`	map	运行时环境变量覆盖。
`metadata`	map	用户侧元数据，便于搜索和调试。
`autoPause`	boolean	支持时可将超时动作映射为 pause 而不是 kill。

不要发送过期兼容字段，例如 timeoutMs、autoResume、secure、allow_internet_access、network、mcp、volume_mounts 或请求级 volumeMounts。这些字段会被拒绝，而不是静默忽略。

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()

原始控制面接口

Method	Path	说明
`POST`	`/api/v1/sandboxes`	创建沙箱。
`GET`	`/api/v1/sandboxes/:sandboxID`	查询详情和运行时连接数据。
`POST`	`/api/v1/sandboxes/:sandboxID/connect`	重连并刷新运行时访问。
`POST`	`/api/v1/sandboxes/:sandboxID/pause`	暂停运行时。
`POST`	`/api/v1/sandboxes/:sandboxID/refreshes`	刷新 TTL。
`POST`	`/api/v1/sandboxes/:sandboxID/timeout`	修改秒级超时。
`DELETE`	`/api/v1/sandboxes/:sandboxID`	删除沙箱。

日志、指标与诊断

信号	路由	用途
沙箱详情	`GET /api/v1/sandboxes/:sandboxID`	状态、运行时 URL/Token、生命周期时间戳、`timeline` 和 `diagnostic`。
沙箱日志	`GET /api/v1/sandboxes/:sandboxID/logs`	启动输出、就绪失败、应用日志和镜像拉取问题。
沙箱指标	`GET /api/v1/sandboxes/:sandboxID/metrics`	当前 CPU、内存、磁盘、网络和任务计数。
可观测性摘要	`GET /api/v1/observability/summary`	用户/项目用量、配额检查、接口可用性和建议动作。