Upstash Box Python SDK
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @org-eyw2ohcx/upstash-skills-upstash-box-py。
技能介绍
要解决什么问题
在本地或自有服务器上跑「带 Shell、Git、定时任务和可选浏览器的隔离环境」,又要让 AI Agent 在容器里按 harness 执行,往往意味着自己拼编排、配额和网络策略。Upstash Box 提供云端沙箱容器;本技能对应的 Python SDK 用来用代码创建与管理 Box,发起 agent run、命令执行、文件与 Git 操作,而不是只做 REST 手工调用。
技能如何工作
通过 UPSTASH_BOX_API_KEY 或构造参数里的 api_key 鉴权后,可用同步 Box 或异步 AsyncBox 操作同一套能力。创建 Box 时可注入账号级环境变量、安装 Context7 格式的 Skills、挂载 MCP 服务器,并为出站流量配置 network_policy。
核心流程大致是:Box 生命周期(创建、快照、from_snapshot 恢复为新实例)→ 在容器内用 box.cd() 维护客户端工作目录(默认 /workspace/home)→ Agent Runs 需指定 harness 与模型(如 ClaudeCode、OpenRouterModel 或带 provider 前缀的字符串),也可跑自定义 harness 进程 → Shell / 文件 / Git(克隆发生在箱内,私有仓需 git.token)→ Schedules 以 UTC Cron 跑命令或 agent 提示 → 可选 browser=True 后在 box.browser 上做页面操作(extract / observe / act 等按量计费)。
EphemeralBox 适合最多 3 天的轻量任务:支持 exec、文件、schedule、快照与网络策略,但不含 agent、git、skills、labels、browser 与公网 URL。需要完整能力时用全功能 Box。
适用边界与注意点
- Agent 配置的入口是
harness(必填),不要再用已废弃的 provider/runner 字段。 run.exit_code仅对 exec 有意义;agent run 为None。成功时run.result多为 stdout,失败时为 stderr。box.cd()只做客户端路径校验与跟踪,不会改变远端 shell 的 cwd;各 SDK 方法会按该目录相对执行。- 删除用
box.delete()不可恢复;需要状态时先快照。流式 run 提前中断时应stream.close()/await stream.aclose(),避免 run 悬挂。 - 超时单位与 JS SDK 一致,均为 毫秒(默认
600000)。
使用场景
- 需要在隔离容器里 clone 不可信仓库并先收紧 network_policy,再只跑 build/test 命令,避免代码落到本机
- 要用异步客户端 asyncio.gather 并行创建多个 AsyncBox 并同时发起 agent.run,做批量代码审查或生成任务
- 在云沙箱里挂 Context7 Skills 与自建 MCP,让 harness 在固定工具集下处理 PR 或内部脚本
- 开启 browser=True 后对页面做 extract/observe/act,把无头浏览器流程和同一 Box 里的 shell、文件操作串在一起
适合人员
- 维护 CI/自动化流水线、需要把 agent 与 cron 调度都放进远端沙箱而非自建 VM 的平台工程师
- 写 Python 集成 Upstash Box、要在 SDK 里区分 Box 与 EphemeralBox 能力边界的后端开发者
- 给 coding agent 接 MCP 与 Skills,且必须用 network_policy 限制出站访问的安全或 DevOps 工程师
- 需要 SSH 进 Box 排障或从快照恢复为新实例做实验复现的 SRE / 支持工程师