Agent Skills
返回列表
💻

Upstash Box 云端沙箱 SDK

开发编程 更新于 2026.08.29

将以下提示词粘贴到你的 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 上的工具链作者,要核对支持矩阵与网络策略