Burrowbox

burrowbox-js

面向 Burrowbox API 的 TypeScript 客户端库：为 AI Agent 提供持久化的 Linux 计算机，每台计算机都配有桌面、保持登录状态的浏览器、凭据库和自己的 MCP 端点。

→ 开始使用 Burrowbox · API 文档

安装

bun add burrowbox

npm（npm install burrowbox）和 pnpm（pnpm add burrowbox）也都可以使用。没有运行时依赖。可在任何提供全局 fetch 的环境中使用：Bun、Node 18+、Deno、Cloudflare Workers。请将 API 密钥保存在服务器上。

快速入门

在 Account → API keys 下创建 API 密钥并导出：

export BURROWBOX_KEY=tmk_...

创建一台计算机，并通过 MCP 将 Agent 连接到它：

import { Burrowbox, toAgentSdkMcpServers } from "burrowbox";
import { query } from "@anthropic-ai/claude-agent-sdk";

const bb = new Burrowbox(); // reads BURROWBOX_KEY

// Boots in a few seconds. It turns itself off (keeping its state) after an hour.
const machine = await bb.machines.create({ name: "research-bot", size: "tiny", ttlMinutes: 60 });

// MCP URL + the machine's scoped token (tmm_…), which only works on this machine.
const mcp = await bb.machines.mcp(machine);

for await (const msg of query({
  prompt: "Open news.ycombinator.com and summarise the top 5 stories.",
  options: { mcpServers: toAgentSdkMcpServers(mcp) },
})) {
  if (msg.type === "result" && msg.subtype === "success") console.log(msg.result);
}

await bb.machines.stop(machine); // files, apps, logins and open windows are kept

mcp 是普通数据（{ name, url, token, headers }），因此可与任何 Streamable HTTP MCP 客户端配合使用。toMessagesApiMcpServer(mcp) 会生成 Anthropic Messages API MCP 连接器所需的结构，而 toClaudeCodeCommand(mcp) 会打印一条 claude mcp add 命令。

功能

• 计算机： 创建、列出、启动、停止、调整规格、安排计划和销毁计算机，还可查看截图、应用和窗口。
• MCP： 获取每台计算机的端点和平台端点的连接详情。
• 实时视图： 获取签名链接，将计算机屏幕嵌入你的产品。你可以选择观看者是否能够接管控制。
• 保管库： 在计算机中存储登录凭据。Agent 可以使用这些凭据，而无需查看它们。
• 预热池： 让计算机保持启动状态，并根据模板完成设置，然后为客户即时分配一台。
• 自动化： 定时任务和 Webhook，可在计算机内运行命令、MCP 工具或 HTTP 调用。
• 事件 Webhook： 计算机状态变化时发送签名通知，并提供 verifyWebhookSignature()。
• 计费和 VPN： 余额、按客户统计的用量，以及住宅 VPN 位置。
• 类型化错误（NotFoundError、InsufficientCreditError、RateLimitError 等）、超时，以及针对幂等请求的自动重试。

const bb = new Burrowbox({
  apiKey: process.env.BURROWBOX_KEY, // or a machine token (tmm_…) for MCP and live-view only
  baseUrl: "https://burrowbox.dev",
  timeoutMs: 60_000,
  maxRetries: 2,
  fetch: customFetch, // optional
});

验证事件 Webhook

import { constructWebhookEvent } from "burrowbox";

// Pass the raw body, not re-serialized JSON. Throws WebhookSignatureError if it doesn't verify.
const event = await constructWebhookEvent(await req.text(), req.headers.get("burrowbox-signature"), process.env.BURROWBOX_WEBHOOK_SECRET!);
if (event.type === "machine.stopped") console.log(event.data.machine.id, event.data.detail);

它使用 Web Crypto，因此同一段代码可以在 Bun、Node、Deno、Workers 和边缘运行时中运行。

完整接口请参阅 API.md。

开发

该仓库使用 Bun 进行安装和运行脚本。测试使用 Vitest，构建使用 tsup（ESM + CJS + 类型）。

bun install
bun run typecheck && bun run test && bun run build
bun run smoke   # import the built package from Node (ESM and CJS)

许可证

MIT