企业官网建设流程全解析

OpenSandbox TTL续期API详解：长时AI任务沙箱保活完整指南

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox

OpenSandbox 是面向 AI Agent 的安全、快速、可扩展的沙箱运行时。沙箱默认带有 TTL（生存时间），到期会自动终止；而它的TTL 续期 API（POST /sandboxes/{sandboxId}/renew-expiration）只需用一个 HTTP 请求就能把沙箱的到期时间往后推，保证长时 AI 任务（爬虫、浏览器自动化、批量推理）不会因为沙箱过期而中途夭折。本文带你快速掌握这个保活 API 的用法、SDK 调用与自动续期技巧。

一、为什么长时 AI 任务需要沙箱 TTL 续期？

AI Agent 的沙箱里经常跑"跑很久"的工作负载：

• 🕷️ 多步骤的网页爬取与浏览器自动化任务
• 🖥️ 长时间有界面操作（如远程桌面会话）
• 🧠 多轮对话 / 多步推理的 Agent 任务

如果沙箱的 TTL 小于任务耗时，任务执行到一半，沙箱就被回收了，上下文全部丢失。解决思路有两个：

1. 手动/周期性续期：在任务关键节点调用 TTL 续期 API 延长expiresAt；
2. 访问自动续期：配置 OSEP-0009，每次访问沙箱自动延长（详见第四节）。

二、TTL 过期机制：timeout 与 expiresAt 的关系

创建沙箱时，请求体中的timeout字段（单位：秒，最小 60）决定沙箱的存活时间：

• 到期后沙箱自动进入Stopping → Terminated状态；
• 省略该字段或置为null可禁用自动过期，改为手动清理（部分运行时不支持无过期沙箱，会拒绝创建）。

过期时间上限由服务器配置server.max_sandbox_timeout_seconds控制。沙箱对象中的expiresAt（RFC 3339 UTC 时间）就是"到期时刻"的绝对时间。完整字段说明见 specs/sandbox-lifecycle.yml。

如何查看当前 expiresAt

用 CLI 的 JSON 列表输出即可看到每个沙箱的expires_at字段：

三、TTL 续期 API 快速上手

1. 接口定义

⚠️两条硬性校验（违反返回 400）：

1. 新的expiresAt必须是未来时间；
2. 必须晚于当前expiresAt——续期只能往后推，不能往回调。

2. 最快发一个续期请求

curl -X POST \ -H "OPEN-SANDBOX-API-KEY: $API_KEY" \ -H "Content-Type: application/json" \ -d '{"expiresAt": "2025-11-16T14:30:45Z"}' \ http://localhost:8080/v1/sandboxes/<sandboxId>/renew-expiration

服务返回 200 时只回传更新后的expiresAt字段，方便你直接落库记录新到期时间。服务端路由实现见 lifecycle.py。

3. 运行时侧发生了什么

以 Docker 运行时为例，续期成功后服务端会做三件事（docker_service.py）：

1. 内存中重新调度过期定时器；
2. 把新到期时间持久化到元数据存储（服务器重启后续期依然有效）；
3. 更新容器 label 中的expiresAt时间戳。

Kubernetes 运行时的对应实现在 kubernetes_service.py。

4. 用 SDK 一行代码续期

各语言 SDK 都封装了这个 API。Python SDK 里直接调用renew_sandbox，传入"从现在起再存活多久"的时长即可，SDK 会自动换算成绝对时间（manager.py）：

from datetime import timedelta await manager.renew_sandbox(sandbox_id, timedelta(hours=2))

同步版本在manager.sync下同名方法，原理相同。

四、进阶：配置"访问即自动续期"（OSEP-0009）

如果你不想在业务代码里手动定时续期，可以启用访问时自动续期：沙箱被流量触达时自动延长，彻底告别保活轮询。

创建沙箱时在extensions中加入一个键即可（OSEP-0009 设计文档）：

• access.renew.extend.seconds：每次访问延长多少秒，取值300 ~ 86400（5 分钟到 24 小时）；
• 省略该键表示关闭；非法值会在创建时直接返回 400。

💡 长连接场景（如 Agent 持续通过 ingress 调用沙箱内服务）下，自动续期基本可以替代手动保活。

五、常见错误码与排查

409 的一个典型细节：对"禁用自动过期"的沙箱调续期，Docker 运行时会返回INVALID_EXPIRATION，提示"does not have automatic expiration enabled"（docker_service.py）。

六、保活最佳实践清单

• ✅按任务阶段续期：在长任务的关键检查点（如每完成一个子步骤）续期，而不是一股脑续到最大；
• ✅续期时长 ≥ 剩余任务预估耗时，并留 20% 左右缓冲；
• ✅续期失败要降级：捕获 409/400 后检查沙箱状态，及时保存进度或重建沙箱；
• ✅能自动就自动：流量持续的场景优先用access.renew.extend.seconds；
• ✅记录每次返回的expiresAt，便于对账与审计。

七、关键资料导航

• 📄 完整 API 规范：specs/sandbox-lifecycle.yml
• 🐍 服务端路由：api/lifecycle.py
• 🐍 Docker 运行时实现：docker_service.py
• 🐍 Kubernetes 运行时实现：kubernetes_service.py
• 🐍 Python SDK 续期封装：sdks/sandbox/python
• 📄 自动续期设计提案：oseps/0009-auto-renew-sandbox-on-ingress-access.md

掌握 TTL 续期 API 后，你的 AI 长任务就能在 OpenSandbox 中"想跑多久跑多久"——既安全隔离，又不被过期机制打断。

【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandbox