A machine is where tools run: a shell, processes, files and, on desktop templates, a display. Every machine runs bmad, the BMA daemon, which dials out to BMA; no inbound port or SSH key is needed. The conversation never lives on the machine, so losing a machine never loses a session.

​
Where machines come from

​
Lazy allocation

A session gets a machine on its first tool call that needs one (run_command, the process tools, storage_upload/storage_download, skill, environment-hosted MCP servers, create_machine). Chat-only sessions, web tools, memory-store tools, questions and custom tools never create a machine, and never count against machine quota.
  • If the tool needs approval (always_ask), BMA asks first; a denied or unanswered request never provisions a machine.
  • If the project’s machine quota is full, the tool call fails with a “no executable machine” result the model can see. The session itself keeps working.
  • This differs from Claude Managed Agents, which starts provisioning when the session is created. The first tool call of a session therefore waits for the sandbox to start.

​
Idle pause and resume

What happens to an idle machine is a pool setting. A pool with pause_after_idle_minutes (at least 5, optionally with delete_after_paused_days) pauses idle machines; a pool with delete_after_idle_minutes deletes them. Ask the BMA team which policy the hosted environment template uses.
  • A machine is not idle while it has queued or running processes, or while someone uses its terminal or desktop.
  • A paused machine keeps its disk and memory; it does not count against quota.
  • The next tool call, terminal, desktop or POST /machines/{machineID}/resume wakes the same machine.
Pools without a pause policy delete idle machines after delete_after_idle_minutes instead.

​
Backup and restore

For persistent machines, BMA periodically backs up the user’s home directory (unchanged content is skipped). If a machine’s host is lost, BMA rebuilds the machine and restores the files from the latest backup. The system layer and running processes are not restored. You can also list backups and restore explicitly: GET /machines/{machineID}/backups, POST /machines/{machineID}/restore.

​
Machine notices

When the machine changes underneath a session, the session gets one event, in order with the other events, and the model is told the same at the start of its next context window so it does not rely on stale files:
Files the agent writes to /mnt/session/outputs are uploaded to BMA as session files, so they survive any of these transitions. See Files & outputs.

​
Connect your own machine

Create a machine record in the project (POST /orgs/{org}/projects/{project}/machines in the native API), install bmad on the computer with the one-time machine token, and grant the machine to the project. Exactly one executor process may represent a computer: a second connection with the same identity replaces the first. For embedding the hand in your own app instead of running bmad, see Executor & brains.