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
}

#Create a machine

POST /api/machines

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

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.

#Updates

Every machine runs the Burrowbox agent (its tools, browser modes, VPN, fixes). New releases reach existing machines without recreating them, and files, apps, logins and the desktop are kept.

• Live updates: the agent restarts in place in about a second. The desktop, open apps and browser keep running, and agents connected over MCP reconnect.
• System updates: packages such as the full browser's Chromium install in the background right after, typically a minute or two.
• Automatic rollout:
  • Running machines with the full browser update live automatically.
  • Machines with the light browser update at their next stop/start. A live restart makes the light browser forget sign-ins, while the full browser keeps them.
  • Set "autoUpdate": false (PATCH /api/machines/{id}) to pin a machine.
• Update now: POST /api/machines/{id}/update, the MCP tool machine_update, or Update available in the dashboard.
• Older machines: machines created before live updates need one save + restart + restore (about 20 seconds). After that their updates are live.
• Status: the machine object shows agentVersion and updateAvailable.

#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:

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}/browser returns the mode and what the running browser supports (webgl, webgl2, renderer).
• Agents: agents on the machine can check with the browser_capabilities tool.
• Warm pools: they take browser too, and their machines boot in that mode.

#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: