burrowbox-js

TypeScript client library for the Burrowbox API: persistent Linux computers for AI agents, each with a desktop, a browser that stays signed in, a credential vault and its own MCP endpoint.

→ Start using Burrowbox · API docs

Install

bun add burrowbox

npm (npm install burrowbox) and pnpm (pnpm add burrowbox) work too. No runtime dependencies. Works anywhere with a global fetch: Bun, Node 18+, Deno, Cloudflare Workers. Keep API keys on your server.

Quickstart

Create an API key under Account → API keys and export it:

export BURROWBOX_KEY=tmk_...

Create a machine and connect an agent to it over 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 is plain data ({ name, url, token, headers }), so it works with any Streamable HTTP MCP client. toMessagesApiMcpServer(mcp) gives the Anthropic Messages API MCP connector shape, and toClaudeCodeCommand(mcp) prints a claude mcp add command.

Features

• Machines: create, list, start, stop, resize, schedule and destroy, plus screenshots, apps and windows.
• MCP: connection details for each machine's endpoint and for the platform endpoint.
• Live view: signed links to embed a machine's screen in your product. You choose whether viewers can take control.
• Vault: store logins in a machine. Agents can use them without ever seeing them.
• Warm pools: keep machines booted and set up from a template, then claim one instantly for a customer.
• Automations: cron jobs and webhooks that run commands, MCP tools or HTTP calls inside a machine.
• Event webhooks: signed notifications when machines change state, plus verifyWebhookSignature().
• Billing and VPN: balance, usage per customer, and residential VPN locations.
• Typed errors (NotFoundError, InsufficientCreditError, RateLimitError…), timeouts, and automatic retries for idempotent requests.

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
});

Verify event webhooks

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);

It uses Web Crypto, so the same code runs in Bun, Node, Deno, Workers and edge runtimes.

The full surface is in API.md.

Development

The repo uses Bun for installs and scripts. Tests run on Vitest, the build on 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)

License

MIT