Burrowbox Docs

Machines

A machine is an isolated Linux computer with its own disk. It keeps its state until you destroy it.

#The machine object

{
  "id": "2f6aeedcd3",
  "name": "acme",
  "status": "running",
  "size": "tiny",
  "screen": "1440x900",
  "expiresAt": 1790797200000,
  "expiresInSeconds": 3540,
  "onExpire": "stop",
  "lastStopMode": null,
  "lastError": null,
  "mcpUrl": "https://burrowbox.dev/api/machines/2f6aeedcd3/mcp",
  "browser": "light",
  "agentVersion": "a-99d2f95985cc",
  "updateAvailable": false,
  "autoUpdate": true,
  "vpn": { "type": "proxy", "country": "de" },
  "externalId": "cus_8f2a",
  "labels": { "plan": "pro", "region": "eu" },
  "poolId": null,
  "pooled": false,
  "createdAt": 1790793600000
}
Field Description
status creating, starting, running, stopping, stopped or error
size tiny (½ vCPU, 4 GB RAM, 8 GB disk), small (1 vCPU, 6 GB, 12 GB), medium (2 vCPU, 8 GB, 16 GB), large (4 vCPU, 12 GB, 20 GB)
expiresAt When the machine will be turned off or destroyed. null means always on
onExpire stop keeps all state; destroy deletes the machine
lastStopMode snapshot (saved on stop) or crashed (stopped unexpectedly; restores from the last save point)
browser light or full — see Browser mode
vpn The machine's VPN location, or null
externalId Your own id for the machine — usually your customer's id. Filter, report usage and receive events by it
labels Free-form key: value strings (up to 20). Keys use letters, digits and _ . : -
poolId The warm pool the machine was claimed from, if any

#Create a machine

POST /api/machines

Body field Type Default
name string generated Up to 48 characters
size string tiny See sizes above
screen string 1440x900 WIDTHxHEIGHT
ttlMinutes number none Keep on for this long, then apply onExpire
onExpire string stop stop or destroy
externalId string none Your customer's id (up to 128 characters)
labels object none e.g. {"plan": "pro"}
browser string light light or full (Chromium with WebGL) — see Browser mode
vpn object none {"type": "proxy", "country": "de"} (or "unlock"); see VPN locations (billed extra)
curl -X POST https://burrowbox.dev/api/machines \
  -H "Authorization: Bearer $BURROWBOX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "acme", "size": "tiny", "ttlMinutes": 60, "externalId": "cus_8f2a", "labels": {"plan": "pro"}}'

Returns 201 with the machine object plus mcpToken. The call returns when the machine is running (usually 1–3 seconds). Returns 402 when your balance is empty.

#List machines

GET /api/machines returns your machines, newest first. Filter with query parameters (all must match):

Parameter
externalId=cus_8f2a Machines tagged with that customer id
label.plan=pro Machines whose label plan is pro (repeat for more labels)
includePooled=1 Also list idle warm pool machines (hidden by default)
curl "https://burrowbox.dev/api/machines?externalId=cus_8f2a&label.region=eu" -H "Authorization: Bearer $BURROWBOX_KEY"

#Get a machine

GET /api/machines/{id} returns the machine object including mcpToken.

#Start and stop

POST /api/machines/{id}/start — optional body {"ttlMinutes": 30} to set a new deadline.

POST /api/machines/{id}/stop

Stopping snapshots the machine's entire filesystem (files, installed apps, the vault, browser cookies including session cookies) and records the open windows and tabs, which reopen on the next start. Memory isn't kept, so running programs are relaunched rather than frozen. While a machine runs, a save point is also taken every 30 minutes.

stop accepts an optional mode for compatibility; it's ignored.

#Change the schedule, name or tags

PATCH /api/machines/{id}

{ "name": "acme-support", "ttlMinutes": 120, "onExpire": "destroy", "externalId": "cus_8f2a", "labels": { "plan": "pro" } }

Set "ttlMinutes": null to make a machine always on. labels replaces the whole set; null clears externalId or labels.

#Waiting for you

Sometimes a machine can't go on until someone answers: a page's confirm("Deseja gravar?"), or a Lacuna Web PKI dialog asking to use a certificate or to sign. While that's open, the page is blocked.

Method Path
GET /api/machines/{id}/pending { "pending": true, "items": [{ "id": "dialog" or "web-pki", "title", "detail", "url", "since", "actions", "todo" }] }
POST /api/machines/{id}/pending/dialog {"action": "accept"} (OK, with text for a prompt) or {"action": "dismiss"} (Cancel)
POST /api/machines/{id}/pending/web-pki {"action": "status"} (returns the dialog as an image), "approve" or "deny"; "remember": true stops asking for that site

Your own app can use these to put a person in the loop: show what's waiting to your user and send their answer.

#Updates

Machines receive new agent releases (tools, browser engines, fixes) without being recreated. Full-browser machines update automatically when idle, while light-browser machines update at their next start or when you call POST /api/machines/{id}/update. The machine object shows agentVersion, updateAvailable and autoUpdate. See Updating machines.

#Change the size

POST /api/machines/{id}/resize with {"size": "medium"} (or PATCH /api/machines/{id} with size).

Also available as the MCP tool machine_resize and in the dashboard (viewer ⋯ → Change size).

#Browser mode

Each machine has one persistent browser, driven by the browser_* tools and shown in the live Browser view. Choose its engine:

Mode Engine WebGL Best for
light (default) Obscura: small, fast, stealth fingerprint No Most sites, forms, scraping, automation
full Chromium, with WebGL 1 and 2 rendered on the CPU (Mesa llvmpipe) Yes Maps, 3D viewers, canvas-heavy web apps, sites that check for WebGL

Machines have no GPU, so full renders graphics in software. Maps, charts and typical WebGL apps work, but animation is slow on small machines, and heavy 3D can drop to a few frames per second. Use medium or large for WebGL-heavy work. full also uses more memory (about 1 GB).

Set it when creating a machine ("browser": "full"), or switch a machine at any time:

curl -X PUT https://burrowbox.dev/api/machines/2f6aeedcd3/browser \
  -H "Authorization: Bearer $BURROWBOX_KEY" -H "Content-Type: application/json" \
  -d '{"browser": "full"}'

#Browser profiles

A machine's browser can hold several profiles: isolated sessions with their own cookies, local storage and open tabs, like Chrome profiles. Use them to stay signed in to several accounts of the same site (work and personal, customer A and B) on one machine. Every machine starts with a profile called default.

Only one profile is live at a time. Switching restarts the browser once (a few seconds) and reopens that profile's saved tabs. Profiles persist across stop/start, and the vault is shared by all of them. The machine must be running.

Method Path
GET /api/machines/{id}/browser/profiles List profiles and the active one
POST /api/machines/{id}/browser/profiles Create: {"name": "acme", "switch": true} (switch is optional)
PUT /api/machines/{id}/browser/profiles/{name} Switch to a profile
DELETE /api/machines/{id}/browser/profiles/{name} Delete a profile and its cookies. Not the default or active one

Names use 1–32 lowercase letters, digits, - or _.

curl -X POST https://burrowbox.dev/api/machines/2f6aeedcd3/browser/profiles \
  -H "Authorization: Bearer $BURROWBOX_KEY" -H "Content-Type: application/json" \
  -d '{"name": "acme", "switch": true}'

#Delete a machine

DELETE /api/machines/{id} permanently deletes the machine: its files, installed apps, vault, browser profile, snapshots, scheduled jobs and webhooks. It can't be undone.

curl -X DELETE https://burrowbox.dev/api/machines/2f6aeedcd3 -H "Authorization: Bearer $BURROWBOX_KEY"
# → {"id": "2f6aeedcd3", "destroyed": true}

Also available as the platform MCP tool machine_destroy, and in the dashboard (the trash icon on a machine, then type its name to confirm).

#Events

GET /api/machines/{id}/events returns the lifecycle log: created, started, stopped (with reason, e.g. balance-empty), expired, error… To be told about these as they happen, register an event webhook.

#Screenshots and apps

These work while the machine is running:

Endpoint Returns
GET /api/machines/{id}/screenshot.jpg?q=60 A JPEG of the desktop
GET /api/machines/{id}/apps Installed desktop applications
GET /api/machines/{id}/windows Open windows with their geometry