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.
- Dashboard: the machine list shows Waiting for you, and the machine's view has a banner with what's pending and buttons to answer it: OK / Cancel for a page dialog, and for Web PKI, Show dialog, Approve / Deny, and "Don't ask again".
- MCP:
machine_pendinglists what's waiting and how to answer each item:browser_dialog, orbrowser_certificate_prompt. Browser tools also report it instead of hanging. - REST:
| 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).
- Running machine: it's saved (files, installed apps, browser logins, open windows and tabs), restarted on the new size, and restored. This takes about 10 seconds, and the response comes back once it's running again.
- Stopped machine: it just starts on the new size next time.
- Billing: the time before the change is charged at the old 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"}'
- Switching: on a running machine the browser restarts once (a few seconds), and open tabs and cookies (including logins) carry over.
PATCH /api/machines/{id}with{"browser": "full"}does the same. - Checking:
GET /api/machines/{id}/browserreturns the mode and what the running browser supports (webgl,webgl2,renderer). - Agents: agents on the machine can check with the
browser_capabilitiestool. - Warm pools: they take
browsertoo, and their machines boot in that mode.
#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}'
- Dashboard: the profile picker in the Browser view's address bar switches or creates profiles.
- Agents on the machine: the
browser_profilestool (list,create,switch,delete). - Platform MCP:
machine_browser_profiles. - Older machines: profiles arrive with the next agent release. Stopped machines get it when they next start; running ones follow the update rules.
- Switching and sign-ins: on the
lightbrowser, a profile's session cookies are kept in an encrypted copy and restored on every switch, so logins survive. Profile storage is included in machine snapshots and deleted with the machine.
#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 |