配置连接
准备有 Box 访问、创建和删除权限的 API key。config 只有size,接受 small、medium、large,默认 small;不要添加其他 Provider 的 CPU、内存或镜像字段。具体规格、额度和账户可用性另行核对,本页不推断固定价格。
以下本地管理客户端示例从私有环境读取 API key,不将它传入 Sandbox。hosted 初始化见自托管。保存返回的连接 ID,重复运行创建示例会得到额外连接。
执行第一项任务
将连接 ID 作为首个 Session的 sandbox_connection_id,并选择兼容模型和 Harness。连接器创建 runtime=node、keepAlive=false 的持久 Box,但 Harness 仍由 Hexagon 选择与安装。分别用 Python 和 TypeScript 核对 Run 完成、文件字节、产物导出与关闭。 当前声明包括 files、commands、preview、pause_resume、filesystem_resume;不包含 OCI 或 network_allowlist。需要受限出站域名的任务应选择支持的 Provider,不能静默降级为 allow-all。 命令通过有远程期限的执行包装运行;后台启动只证明进程启动受理,还要观察 Runtime 健康或应用端口。不要以命令提交成功代替任务完成,也不要在完成状态未知时重复外部副作用。私有 HTTP 与传输限制
私有预览通过已鉴权 exec session 的 stdin/stdout 转发到 Sandbox 内端口,不依赖公开端口 URL。账户 API key 留在控制平面,Runtime 和预览授权仍独立检查。预览服务必须在目标端口实际运行。 当前 Upstash relay 的限制是:
8 MiB 不是总响应体大小上限。 持续消费的流可以分批通过,但不能由此承诺任意大小传输。更上层 API、产物或代理可能有独立限制;大文件应分别验证完整性、总量、慢读和中断行为。超过限制时传输失败,不能把截断内容当成功结果。
暂停与下一轮
平台空闲策略调用 pause,下一轮 submit 自动 resume 并恢复 Runtime。受管理文件与对话数据按文件系统策略保留;进程内存、打开的网络连接和任意服务不在保证内。不要把 inspect 映射出的 running 状态理解成此刻一定有活跃 CPU:连接器将 Provider idle 规范化为 running,以表示资源存在。 验证时先写入已知文件并记录对话测试值,等待目标空闲条件,再向同一 Session 提交第二轮,检查真实读取与对话继续。Python 与 TypeScript 独立完成;需要预览时复核服务是否需重新启动。参见空闲与唤醒。期限与关闭
控制平面负责持久期限和最终删除。暂停保留 Box,不释放全部资源;本地控制平面停止也不保证远程 Box 到期删除。关闭之后必须确认 Box 不存在,不能以 pause、idle 或删除请求被接受代替确认。 创建使用持久 operation ID 派生的名字与 hexagon label;响应丢失后查找原名字。删除后仍能 inspect 到资源时返回 upstash_deletion_unconfirmed。只有供应商 404 被当作不存在,鉴权或网络错误保留不确定结果。按对账指南处理原资源,不新建一批来验证上一批是否成功。故障与验收范围
鉴权错误检查 key 与账户权限;分配错误检查 size 和额度;后台启动未知检查原进程与 Runtime;隧道断开检查服务、exec 通道和输出消费;buffer_limit 与 request_limit 分别对应输出排队与输入累计。报告中不要包含原始 API key 或未经脱敏的任务内容。 成功条件包含实际任务、二进制文件完整性、私有访问、两轮文件与对话连续性、关闭后资源不存在和产物仍可读。历史扩展矩阵可能包含早期路线,当前恢复策略应结合serverless 矩阵逐项看范围。本页是源码核对,没有新执行实云任务。 依据:Box 连接器、传输实现。下一步:Sandbox 总览、产物。区分慢消费者与过大的请求
消费者尚未读走 7 MiB 排队输出,又收到 2 MiB 时,可能因缓冲压力失败。这不表示每个 9 MiB 响应都被禁止。相反,一条 relay 中累计 17 MiB 的请求,即使按小块发送,也超过 16 MiB 输入预算。这些限制都不会覆盖 Hexagon 其他层更小的初始上传、产物或代理限制。 遇到upstash_tunnel_buffer_limit 或异常退出,不能将已收到的前缀当作完整文件。保留操作身份,重试前核对底层请求是否有副作用。纯下载应按预期大小和 hash 拒绝不完整内容。Relay 测试使用模拟 exec session 检查精确字节与 EOF、慢读取时的过大输出及异常远端退出,不是大型文件的真实 Box 传输验收。
历史 Box 记录包含早期 EphemeralBox 调查。当前接入以连接器为准,persistent Box 下一轮证据见 serverless 记录。不要将早期原生 TTL 或不支持 pause 的描述复制到当前配置步骤。
依据:当前生命周期契约。下一步:私有预览、空闲唤醒、限制。