Burrowbox MCP server
Commit Oct 3, 2026Provides persistent Linux computers for AI agents featuring desktops, signed-in browsers, credential vaults, and dedicated MCP endpoints.
Also known as burrowbox/burrowbox-js, burrowbox-js
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 1.0.0
- Last commit
- Oct 3, 2026
- License
- MIT
What is Burrowbox MCP?
Burrowbox provides persistent Linux computers for AI agents featuring desktops, signed-in browsers, credential vaults, and dedicated MCP endpoints.
Summary generated from the project's README
About Burrowbox MCP server
Burrowbox provides persistent Linux computers designed specifically for AI agents. These machines include a desktop environment, browsers that maintain active login sessions, and a credential vault that allows agents to use logins without seeing the actual credentials. Developers can manage these machines through a TypeScript client library that works across Bun, Node 18+, Deno, and Cloudflare Workers using a global fetch.
Users connect agents to these environments via dedicated MCP endpoints. Each machine provides its own scoped token and URL, making it compatible with any Streamable HTTP MCP client. The platform supports advanced management features such as warm pools for instant machine claiming, cron job automations, and live view links to embed a machine's screen into other products. You can control machine lifecycles by creating, resizing, or stopping instances, which preserves files, applications, and open windows for later use.
What you can do with it
- 1Automated web researchInstruct an agent to visit a specific website and summarize the current top news stories.
- 2Secure credential managementAllow an AI agent to perform tasks on websites using stored logins without exposing the sensitive data to the model.
- 3Persistent agent environmentsRun a task on a machine that saves its current state, including open windows and files, even after it stops.
- 4Scheduled task executionSet up automated commands or MCP tools to run inside a Linux machine at specific intervals.
Written from the project's README. Every use case is checked against a quote from it.
How to install Burrowbox MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Burrowbox MCP in Claude Code
$ claude mcp add --transport http burrowbox-js https://burrowbox.dev/mcpInstall Burrowbox MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"burrowbox-js": {
"url": "https://burrowbox.dev/mcp"
}
}
}Install Burrowbox MCP in VS Code
.vscode/mcp.json
{
"servers": {
"burrowbox-js": {
"type": "http",
"url": "https://burrowbox.dev/mcp"
}
}
}Install Burrowbox MCP in VS Code CLI
$ code --add-mcp '{"name":"burrowbox-js","type":"http","url":"https://burrowbox.dev/mcp"}'Install Burrowbox MCP in Codex
$ codex mcp add burrowbox-js --url https://burrowbox.dev/mcpInstall Burrowbox MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.burrowbox-js] url = "https://burrowbox.dev/mcp"
Install Burrowbox MCP in Gemini CLI
$ gemini mcp add -s user --transport http burrowbox-js https://burrowbox.dev/mcpInstall Burrowbox MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"burrowbox-js": {
"url": "https://burrowbox.dev/mcp",
"type": "http"
}
}
}Configuration
BURROWBOX_KEY
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableburrowbox/burrowbox-js is public and reachablegithub.com/burrowbox/burrowbox-js ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-04github.com/burrowbox/burrowbox-js ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeHTTPS endpoint answered 401 (sign-in required)Pass
README
View on GitHubburrowbox-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
Burrowbox MCP questions
How do I add Burrowbox MCP to Claude Code?
Run claude mcp add --transport http burrowbox-js https://burrowbox.dev/mcp in your terminal. Add --scope user to make it available in every project.
How do I add Burrowbox MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What happens to the machine state when it stops?
Files, applications, logins, and open windows are all preserved when a machine is stopped.
How can I use the machine's credentials securely?
The Vault allows agents to use stored logins without ever actually seeing the credentials themselves.
Can I embed the machine's screen in my own application?
Yes, Burrowbox provides signed links that allow you to embed a machine's live view into your product, with options to control viewer permissions.