Warm pools

A warm pool keeps machines booted and waiting, so when a customer needs a desktop you hand one over instantly instead of waiting for a boot. Claiming a machine tags it for that customer; the pool refills itself in the background (within about a minute).

• Idle pool machines are billed like running machines. A pool of 3 tiny machines costs about $0.21/h.
• Idle pool machines are hidden from GET /api/machines (add includePooled=1 to see them) and don't send events. Once claimed, a machine is an ordinary machine: it sends machine.claimed and then its normal events.
• If the pool is empty when you claim, a new machine is booted with the pool's settings (a few seconds) and the response says "fromPool": false.

#The pool object

{
  "id": "pool_3fa91c", "name": "support-desk", "size": "tiny", "screen": "1440x900",
  "target": 3, "ready": 3, "warming": 0,
  "setup": [{ "type": "tool", "tool": "apps_install", "arguments": { "kind": "apt", "packages": ["gimp"] } }],
  "paused": false, "setupFailures": 0,
  "lastSetup": { "at": 1790797200000, "ok": true, "machineId": "7c1e40a2f9", "durationMs": 41200, "output": "### step 1/1 · tool apps_install · ok · 41s\n…" },
  "createdAt": 1790793600000
}

target is how many idle machines to keep (0–10). ready are set up and waiting; warming are booting or running the template.

#Templates

A pool can carry a template: setup steps every new pool machine runs before it counts as ready. Install your customer's apps, clone a repo, open your web app on its login page. Claiming a machine hands over a desktop that's already set up, with no install time.

Steps use the same format as scheduled job actions: shell, tool (any machine MCP tool) or http. Up to 10, run in order.

"setup": [
  { "type": "tool", "tool": "apps_install", "arguments": { "kind": "apt", "packages": ["gimp", "libreoffice"] } },
  { "type": "shell", "command": "pip install --user pandas && git clone https://github.com/acme/tools ~/tools", "timeoutSeconds": 900 },
  { "type": "tool", "tool": "browser_navigate", "arguments": { "url": "https://app.example.com/login" } }
]

• Order. Steps stop at the first failure. A shell step fails on a non-zero exit, and a tool step fails on a tool error.
• Limits. A shell step can run for up to 15 minutes (timeoutSeconds, max 900). The whole setup can take up to an hour.
• Failures. When setup fails, that machine is destroyed and the pool builds a new one. After 3 failures in a row the pool pauses ("paused": true) so a broken template doesn't keep billing you. Fix the template, or send any PATCH (even an empty body) to resume.
• Setup log. lastSetup holds the output of the most recent setup. The dashboard shows it under Warm pools.
• Changes. Changing setup (or size/screen) rebuilds the idle machines. Machines already claimed keep what they have.
• Empty pool. If a claim finds the pool empty, the new machine runs the template too. It's usable right away, while setup finishes in the background, and the response includes "setup": "pending".

In the dashboard, open Warm pools → Template. The simple form covers apt packages, a setup script and a page to open, and "Advanced" takes the raw JSON steps.

#Endpoints

#Claim a machine

POST /api/pools/{id}/claim

curl -X POST https://burrowbox.dev/api/pools/pool_3fa91c/claim \
  -H "Authorization: Bearer $BURROWBOX_KEY" -H "Content-Type: application/json" \
  -d '{"name": "acme", "externalId": "cus_8f2a", "ttlMinutes": 30}'

Returns the machine object with mcpToken and "fromPool": true (status 200), or "fromPool": false with status 201 when a new machine had to be booted.

A claimed machine is brand new: nothing from other customers is on it. Pool machines are never reused after being claimed.

#From an agent

Platform MCP tools: pools_list, pool_create, pool_update, pool_delete, pool_claim.