生命周期与连接

创建 Sandbox 失败，先查什么？

先查四项：API Key 是否正确，E2B_API_URL 和 E2B_DOMAIN 是否同地域，模板名称是否存在，账号是否有权限和配额。

建议先运行最小示例。如果最小示例失败，问题通常在鉴权、Endpoint、地域或配额；如果最小示例成功，再排查自定义模板和业务命令。

创建成功但马上不可用，怎么办？

先执行最小命令确认通道是否可用：

echo ok

如果最小命令可用，问题多半在业务命令、依赖、工作目录或权限。如果最小命令不可用，检查 Sandbox 状态、模板启动逻辑和服务侧错误。

Sandbox.connect(sandboxId) 失败，常见原因是什么？

常见原因是 sandboxId 不属于当前账号或地域、Sandbox 已被 kill()、已超时回收，或 SDK 版本不匹配。

业务侧应保存 sandboxId、模板、任务 ID 和创建时间。连接后建议执行一次轻量健康检查，不要默认原来的进程、端口服务和外部连接仍然可用。

pause() 和 kill() 怎么选？

任务还要继续、需要保留现场，用 pause()。任务完成、失败不可恢复或超过业务等待时间，用 kill()。

暂停与恢复功能当前仅对已开通白名单的账号可用。未开通白名单时，应调用 kill()，并在任务恢复时重新创建 Sandbox。

暂停用于保留 Sandbox 现场，后续通过连接同一个 sandboxId 恢复。不要把 kill() 当作暂停使用；kill() 后不能回到同一个运行现场。

暂停后恢复，状态一定还在吗？

暂停/恢复用于保持 Sandbox 状态。恢复后，业务侧仍建议做一次轻量健康检查，确认命令通道、关键文件和服务端口符合预期。

如果状态需要跨 Sandbox、跨地域或长期审计留存，应同步写入外部存储或业务数据库。

忘记 kill() 会有什么影响？

Sandbox 会继续占用资源，直到主动终止、超时或平台回收。生产代码应使用 try/finally 或等价机制释放资源。

try {
  await sandbox.commands.run("python3 main.py", { timeoutMs: 120_000 });
} finally {
  await sandbox.kill();
}

Sandbox 如何支持 longrun？

longrun 场景应明确三件事：Sandbox 生命周期、命令/服务运行方式、业务侧恢复策略。

对于需要持续运行的 Agent、代码解释器、自动化任务或沙箱内 Web 服务，应保存 sandboxId，记录关键进程和端口，并在恢复连接后做健康检查。任务完成后再调用 kill() 释放资源。