Skip to main content
Agent Swarm's hexagon mark and name inside the boxd card. Agent Swarm is an open-source agentic operating system for your company: a lead agent hands tasks to specialized worker agents, and their memory, skills, and workflows build up with every run. Its runtime pools, in beta, start workers on demand when tasks need capacity and stop them when the work is done. The boxd runtime provider starts each worker on its own isolated boxd machine, which runs the pool’s worker image in its own Docker daemon. It takes the same worker images as Docker pools, and it ships in Agent Swarm v2.7.4 and later.

​
Set up

1

Create an API key

Machines are created and billed in the key’s organization.
2

Turn on runtime pools and add the key

On the Agent Swarm API:
Restart the API. It seeds an online builtin-boxd controller.
3

Create a boxd pool

Create a pool with kind: "boxd" on the builtin-boxd controller, and bind your coding agents to it. Agent Swarm recommends delivery: "push" with on-demand capacity and minRuntimes: 0, so an agent sleeps when no work is left. The machine connects back to the API, so the API needs a public HTTPS URL.

​
Start workers in seconds from a snapshot

A fresh machine pulls the worker image every time a worker starts. Save a snapshot of a machine that already has the image, set BOXD_SNAPSHOT in the controller configuration, and a worker starts in about 3 seconds:
A machine from a snapshot keeps the size it was saved at.

​
Controller settings

Machines have no lease of their own: each runs until Agent Swarm stops its worker. Keep the API running, or set BOXD_DELETE_AFTER_SEC. When the API can’t reach boxd itself, run a remote controller elsewhere with agent-swarm controller --kind boxd, BOXD_API_KEY, and MCP_BASE_URL set to the API’s public URL.

​
What each worker gets

  • Isolation: every machine is created isolated, with no metadata endpoint, no in-machine boxd CLI or account integrations, and no route to your organization’s other machines.
  • Docker inside: the worker image runs in the machine’s own Docker daemon, the same image a Docker pool runs.
  • A size: the smallest of boxd’s machine sizes that covers the pool’s resources: 1 vCPU and 4 GiB, 2 and 8, 4 and 16, or 8 and 32.
  • A deadline you can count on: with BOXD_DELETE_AFTER_SEC, the machine gets a delete-after timer. If boxd refuses the timer, Agent Swarm deletes the machine rather than leave it running without one.
  • A confirmed teardown: stopping a worker succeeds only once boxd reports its machine gone.
Agent Swarm’s runtime pools guide covers pools, controllers, and push delivery in full.