Burrowbox

io.github.burrowboxv1.0.0Updated Oct 4, 2026

Persistent Linux computers for AI agents: desktop, signed-in browser, vault, apps and shell.

VerifiedStreamable HTTPWeb executableDeveloper Tools Cloud & Infrastructure Security & Monitoring

Overview

AI-generated overview

Gives an assistant a persistent Linux machine with a desktop, a signed-in browser, a credential vault, apps and a shell, reachable over MCP.

What it does: Burrowbox provides persistent Linux computers for AI agents, each with a desktop, a browser that stays signed in, a credential vault and its own MCP endpoint. The platform endpoint and per-machine endpoints expose connection details, and machines can be created, listed, started, stopped, resized, scheduled and destroyed, with screenshots, apps and windows. A vault stores logins that agents can use without seeing them, and automations run cron jobs and webhooks inside a machine.
When to use it: Use it when an assistant needs a real, stateful computer rather than a stateless tool call: keeping a browser session signed in, running shell commands and desktop apps, or holding credentials across sessions. It also suits products that hand a preconfigured machine to a customer from a warm pool.
Requirements: A remote endpoint at burrowbox.dev over Streamable HTTP. An Authorization header with a Burrowbox API key (tmk_...) from Account to API keys is required; machine tokens (tmm_...) are scoped to one machine. The README's client library reads BURROWBOX_KEY and needs a global fetch (Bun, Node 18+, Deno, Workers).

Before you install

The Authorization header carries a Burrowbox API key, a secret that should stay on the server. Machines are billed, and errors such as InsufficientCreditError indicate spending; check balance and usage. Machines run commands, apps and automations, and live-view links can be shared with control enabled, so review what is exposed. Vault credentials are usable by agents, and webhook payloads should be verified with the signing secret.

Installation

In SourceWeft

Open Burrowbox in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "burrowbox": {
      "type": "http",
      "url": "https://burrowbox.dev/mcp"
    }
  }
}

README

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

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:

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

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

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

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

bash

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

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

License

MIT

Source: README.md at commit d668007

Tools

Tool metadata has not been indexed yet.

Version history

v1.0.0LatestOct 4, 2026