Machine pool and machine budget
- Desktop app
- All plans
What it does
For people who run AgentsRoom on several computers of the same account (an always-on box and a laptop or office PC). Each project gets an ordered list of the computers its agents may start on, the machine pool. Every start goes to the first computer of the pool that is online, has the project and still has room, so work lands where there is capacity and moves to the next computer when the preferred one is full, asleep or switched off. Each computer also gets a budget (maximum live agents, a free memory floor, a stricter night window) so that many open projects can no longer run one machine out of memory. A project that lives on another computer shows its full workspace from this one: files, changes, backlog and the bottom terminals.
Where to find it
- Pool: Project settings > Machines.
- Budget of this computer: Settings > Agent behavior > Budget of this computer.
- Budget of any computer of the account: the Machines chip in the status bar, then the gauge button at the end of a computer's row.
- Quick agent: the "Launch on" section at the bottom of the ⚡ menu offers "Automatic (machine pool)", armed by default when the project has a pool.
- Triggers: trigger editor > Run settings > Machines > "Machine pool".
- Full workspace of a project that lives on another computer: open it from the sidebar ("On my other machines"), then Files, Changes or Backlog in its header.
- On the phone: project menu > Machine pool (pool and budgets), the gauge button of the Remote screen (budgets of every computer), the "Automatic (machine pool)" row of the ⚡ sheet, the "Machine pool" choice of a trigger's Machines field, and the files / changes buttons next to a machine in Remote.
How to use it
- Open Project settings > Machines, tick at least two computers and order them, the preferred one first (the always-on box, typically).
- Optionally set a budget on each computer (Machines chip > gauge button).
- Work as usual. Opening an agent, Start on a ticket, the ⚡ quick agent and triggers set to "Machine pool" now start on the first computer of the pool with room. A machine picked by hand ("Run on", "Launch on") always wins.
An agent whose conversation lives on THIS computer keeps starting here while this computer is in the pool and has room: elsewhere it would start blank. Moving it with its conversation is "Continue the conversation on".
When you start an agent yourself and this computer is past its budget, a
dialog offers to start it on another computer of the account that has room,
to start it here anyway, or to cancel. A start the app makes on its own (a
trigger, agents_spawn, a ticket started by an agent, a team step) never asks:
it waits for room and starts by itself once an agent ends or memory frees.
While it waits, its tab says why ("Waiting for room", "Waiting for memory",
night budget) with a Start now button, which goes through the same dialog
as a start of your own. The agent that called agents_spawn sees the run as
held with a heldReason in agents_spawned_get / agents_spawned_wait, so
it can tell you instead of waiting (since 2026-10-29). The plan's limit of
agents running at once and a quota rule that refuses the launch show the same
way (plan_limit, quota_rule); a quota refusal does not start by itself.
A start asked by another computer is refused with the reason ("at its budget",
"short of free memory", "night budget").
Settings
machinePool(project, Project settings > Machines): ordered device ids of the account's computers. Fewer than two computers = off (default).machineBudget(global, Settings > Agent behavior > Budget of this computer, also editable for any computer from the Machines chip):{ maxAgents?, minFreeMemMB?, night?: { start, end, maxAgents } }, null = no limit (default). Stored on the account, applied by the computer itself, in its local time.- Trigger
machineScope: "pool"(trigger editor > Machines > Machine pool): one run per occurrence on the pool,deviceIdsignored.
Agent tools (MCP)
agents_spawnwithmachine: "auto" lets the project's pool decide, a machine name or device id picks one, omitted = this computer (a project with no folder here goes to the computer that has it). Over there the agent runs on that computer's own account;agents_spawned_get/agents_spawned_waitonly follow this computer's runs.triggers_savewithmachineScope: "pool".settings_setwithmachinePool(scope project) ormachineBudget(scope global, this computer).
Providers
All providers, no difference: placement decides WHERE the agent CLI starts, the CLI itself is resolved on the computer that runs it.
Mobile
The phone shows each computer's load and budget and edits budgets, edits the project's pool, offers "Automatic (machine pool)" in the ⚡ sheet, sets a trigger to "Machine pool", and browses the files and changes of a project that lives on another computer.
Limits
- Needs Remote Fleet (the computers signed in to the same account and connected). Placement reads the load each computer announces every 30 seconds, so two starts in the same instant may both land on a computer that had room for one; the computer's own budget then makes the second one wait.
- The agent count includes every agent console of the computer (all projects, all windows, the phone's starts). An agent offloaded over SSH counts on the computer that opened it.
- A trigger set to "Machine pool" runs once per occurrence. The preferred computer gets three minutes to take it, then any computer of the pool may. When none could and the trigger does not catch up, the run is recorded as missed and you get a notice on the desktop and the phone.
- A project shared by another account never shows its files or changes here, and is never part of a pool.
- Files of another computer are read-only here; Changes can commit and push on that computer. Very large files are not shown.
Common questions
-
A computer says "Does not have this project open". It has no folder open for this project, or it opened a clone under another identity. Open the folder there: a clone with no
.agentsroom/project.jsonjoins the project of your account. On a server,agentsroom --server --open <folder>also folds back a duplicate made by an earlier version (see Linux Server Mode). -
Can I change the machine pool or a computer's budget from my phone? Yes. The budget of any computer is saved on your account from the phone (Remote screen, gauge button), even when that computer is off. The pool of a project (project menu > Machine pool) is saved through your paired computer, which must be online.
-
Can AgentsRoom start my agents on the least loaded machine automatically? Yes: set a machine pool in Project settings > Machines. Each start goes to the first computer of the pool with room, the next one when it is full or off.
-
How do I stop 20 open projects from running my server out of memory? Set that computer's budget (Machines chip > gauge button): a maximum of live agents and a free memory floor, all projects together.
-
Can the assistant on my laptop start an agent on my always-on box? Yes: ask it, it passes
machine("auto" or the box's name) toagents_spawn. -
Do triggers still run when my laptop sleeps? With "Machine pool" set on the trigger and the always-on box in the pool, the box runs it, once.
-
An agent started by another agent stays "starting" and never launches. Why? Open its tab: when the app holds it back, the tab says why (this computer's budget is full, free memory is under its floor, the night budget, the plan's agent limit, or a quota rule) and offers Start now. The spawning agent reads the same reason (
state: "held",heldReason). Raise or clear the budget in Settings > Agent behavior > "Budget of this computer" if the hold is not what you want. -
Can I see the files and Git of a project that only exists on my other computer? Yes: open the project, then Files or Changes in its header.
Related
- Remote Fleet: the connection between the account's computers this builds on.
- Remote Agent Control: driving an agent of another computer.
- Scheduled Tasks: triggers and their machine scope.
- Webhook Triggers: a webhook event is already consumed once.