Burrowbox

burrowbox-js

Burrowbox API 用の TypeScript クライアントライブラリです。AI エージェント向けの永続的な 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 経由でエージェントを接続します。

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： 各マシンのエンドポイントとプラットフォームのエンドポイントの接続情報を取得できます。
• ライブビュー： マシンの画面を製品に埋め込むための署名付きリンクを利用できます。閲覧者に操作を許可するかどうかは選択できます。
• 保管庫： マシンにログイン情報を保存できます。エージェントはログイン情報を見ることなく利用できます。
• ウォームプール： テンプレートからマシンを起動してセットアップした状態に保ち、顧客向けに即座に確保できます。
• 自動化： マシン内でコマンド、MCP ツール、HTTP 呼び出しを実行する cron ジョブと Webhook に対応します。
• イベント 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 + types）を使用します。

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

ライセンス

MIT