OpenSandbox TTL续期API详解：长时AI任务沙箱保活完整指南
OpenSandbox TTL续期API详解长时AI任务沙箱保活完整指南【免费下载链接】OpenSandboxSecure, Fast, and Extensible Sandbox runtime for AI agents.项目地址: https://gitcode.com/GitHub_Trending/ope/OpenSandboxOpenSandbox 是面向 AI Agent 的安全、快速、可扩展的沙箱运行时。沙箱默认带有 TTL生存时间到期会自动终止而它的TTL 续期 APIPOST /sandboxes/{sandboxId}/renew-expiration只需用一个 HTTP 请求就能把沙箱的到期时间往后推保证长时 AI 任务爬虫、浏览器自动化、批量推理不会因为沙箱过期而中途夭折。本文带你快速掌握这个保活 API 的用法、SDK 调用与自动续期技巧。一、为什么长时 AI 任务需要沙箱 TTL 续期AI Agent 的沙箱里经常跑跑很久的工作负载️ 多步骤的网页爬取与浏览器自动化任务️ 长时间有界面操作如远程桌面会话 多轮对话 / 多步推理的 Agent 任务如果沙箱的 TTL 小于任务耗时任务执行到一半沙箱就被回收了上下文全部丢失。解决思路有两个手动/周期性续期在任务关键节点调用 TTL 续期 API 延长expiresAt访问自动续期配置 OSEP-0009每次访问沙箱自动延长详见第四节。二、TTL 过期机制timeout 与 expiresAt 的关系创建沙箱时请求体中的timeout字段单位秒最小 60决定沙箱的存活时间到期后沙箱自动进入Stopping → Terminated状态省略该字段或置为null可禁用自动过期改为手动清理部分运行时不支持无过期沙箱会拒绝创建。过期时间上限由服务器配置server.max_sandbox_timeout_seconds控制。沙箱对象中的expiresAtRFC 3339 UTC 时间就是到期时刻的绝对时间。完整字段说明见 specs/sandbox-lifecycle.yml。如何查看当前 expiresAt用 CLI 的 JSON 列表输出即可看到每个沙箱的expires_at字段三、TTL 续期 API 快速上手1. 接口定义项目说明方法POST路径/sandboxes/{sandboxId}/renew-expiration请求头OPEN-SANDBOX-API-KEY: 你的API Key请求体{expiresAt: 2025-11-16T14:30:45Z}响应200返回新的expiresAt400/401/403/404/409/500表示失败⚠️两条硬性校验违反返回 400新的expiresAt必须是未来时间必须晚于当前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内存中重新调度过期定时器把新到期时间持久化到元数据存储服务器重启后续期依然有效更新容器 label 中的expiresAt时间戳。Kubernetes 运行时的对应实现在 kubernetes_service.py。4. 用 SDK 一行代码续期各语言 SDK 都封装了这个 API。Python SDK 里直接调用renew_sandbox传入从现在起再存活多久的时长即可SDK 会自动换算成绝对时间manager.pyfrom datetime import timedelta await manager.renew_sandbox(sandbox_id, timedelta(hours2))同步版本在manager.sync下同名方法原理相同。四、进阶配置访问即自动续期OSEP-0009如果你不想在业务代码里手动定时续期可以启用访问时自动续期沙箱被流量触达时自动延长彻底告别保活轮询。创建沙箱时在extensions中加入一个键即可OSEP-0009 设计文档access.renew.extend.seconds每次访问延长多少秒取值300 ~ 864005 分钟到 24 小时省略该键表示关闭非法值会在创建时直接返回 400。 长连接场景如 Agent 持续通过 ingress 调用沙箱内服务下自动续期基本可以替代手动保活。五、常见错误码与排查状态码场景排查建议400expiresAt非未来时间或不晚于当前值检查时间格式RFC 3339 UTC与取值401 / 403API Key 缺失 / 无权限确认OPEN-SANDBOX-API-KEY正确404沙箱不存在或已终止先GET /sandboxes/{id}确认状态409沙箱是手动清理模式创建时未设timeout或过期元数据缺失无 TTL 的沙箱天然无需续期属正常冲突409 的一个典型细节对禁用自动过期的沙箱调续期Docker 运行时会返回INVALID_EXPIRATION提示does not have automatic expiration enableddocker_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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考