Upstash Box 云端沙箱 SDK
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/upstash-skills-upstash-box-js。
技能介绍
要解决什么问题
本地跑不可信仓库的构建脚本、给 Agent 开 Shell 和 Git、或需要带公网出口的隔离环境时,开发机既难做网络隔离,也难保证「克隆代码 ≠ 在你机器上执行」。Upstash Box 提供账号级沙箱容器,本技能把 @upstash/box SDK 的生命周期、运行模型和常见坑整理成可检索的参考,方便在应用里编排容器而不是死记 API 碎片。
技能覆盖的核心能力
- 环境与鉴权:通过
UPSTASH_BOX_API_KEY或构造参数传入apiKey;账号级环境变量会注入到每个 Box。 - Agent 运行:
harness为必填(provider/runner已废弃);可选用托管 harness 枚举,或用 Custom harness 在箱内跑自有 Agent 二进制。 - Shell 与文件系统:
exec、文件读写等操作相对客户端跟踪的 工作目录 执行;默认 cwd 为/workspace/home,box.cd()仅在 SDK 侧校验路径,不改变容器内 shell 的 cwd。 - Git:克隆发生在 Box 容器内;对不可信仓库应配合 networkPolicy 再执行 build/test。
- 定时任务:Box 与 EphemeralBox 支持 UTC Cron(shell 或 Agent prompt)。
- 快照与恢复:无
box.fork(),需先快照再用Box.fromSnapshot()新建实例。 - 浏览器:创建时
browser: true才可用无头 Chromium;extract/observe/act/run为计费 AI 能力。 - EphemeralBox:轻量、最长约 3 天;支持 exec、文件、schedule、快照与网络策略,不支持 agent、git、skills、browser、公网 URL。
- 扩展:从 Context7 安装 Skills(
owner/repo/skill-name)、挂载 MCP Servers、公网暴露端口、Labels 与出站 networkPolicy。
边界与注意点
Agent 运行的 run.exitCode 为 null;run.result 成功时为 stdout、失败时为 stderr 摘要,仅 stderr 输出成功时需读 run.stderr。box.delete() 不可恢复,删前宜快照。私有仓 Git/PR 需在 BoxConfig 配置 git.token。responseSchema 与 browser schema 依赖 zod(v3/v4)。遥测默认开启,可用 UPSTASH_DISABLE_TELEMETRY 或 enableTelemetry: false 关闭。
使用场景
- CI 外需要在隔离容器里克隆第三方仓库并只在该环境内跑测试,避免污染本机
- 产品后台要为每个用户会话创建 EphemeralBox,定时用 Cron 执行清理或巡检 shell
- Agent 工作流要在沙箱内挂载 Context7 Skill 与自管 MCP,并对不可信输入收紧 networkPolicy
- 调试无头页面时创建带 browser 的 Box,在 Tab 上做 observe/act 而非在本机起 Chromium
适合人员
- 维护多租户 Agent 产品的后端工程师,要把 exec/git/定时任务放进独立容器而非共享 VM
- 集成 Upstash Box 的 TypeScript 开发者,需要弄清 harness、cwd 与 Run 字段语义避免排错走弯路
- 安全评审要求先沙箱再执行不可信 Git 仓库构建的安全工程师或平台 SRE
- 需要把 MCP 与 Registry Skills 接到 Box Agent 上的工具链作者,要核对支持矩阵与网络策略