> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Swarm

> Start Agent Swarm workers on demand, each on its own isolated boxd machine with its own Docker daemon.

![Agent Swarm's hexagon mark and name inside the boxd card.](https://mintcdn.com/azin/MZsNmTcqairiWETw/images/boxd-x-agent-swarm.png?fit=max\&auto=format\&n=MZsNmTcqairiWETw\&q=85\&s=17857de9b9b43bbf1746e56c466cbf8d)

[Agent Swarm](https://agent-swarm.dev) 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](https://github.com/desplega-ai/agent-swarm/pull/2354) 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**

```bash theme={"theme":"github-dark"}
boxd auth keys create agent-swarm --org <your-org>
```

Machines are created and billed in the key's organization.

**2. Turn on runtime pools and add the key**

On the Agent Swarm API:

```bash theme={"theme":"github-dark"}
RUNTIME_POOLS_ENABLED=true
MULTI_RUNTIME_ENABLED=true
BOXD_API_KEY=bxd_...
```

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](https://docs.boxd.sh/guides/snapshots.md) of a machine that already has the image, set `BOXD_SNAPSHOT` in the controller configuration, and a worker starts in about 3 seconds:

```bash theme={"theme":"github-dark"}
boxd machine new swarm-base --isolated
boxd machine exec swarm-base -- docker pull ghcr.io/desplega-ai/agent-swarm-worker:slim
boxd snapshots save swarm-base swarm-worker-slim
boxd machine remove swarm-base --confirm
```

A machine from a snapshot keeps the size it was saved at.

## Controller settings

| Setting | What it does |
| - | - |
| `BOXD_SNAPSHOT` | Restore this snapshot instead of booting a fresh machine. |
| `BOXD_DELETE_AFTER_SEC` | Delete each machine this many seconds after it's created, whatever state it's in. A safety net for per-task pools. |
| `BOXD_ORG` | The organization for a personal API key. An organization's key already selects its own. |
| `BOXD_START_TIMEOUT_SEC` | How long `docker run` may take to start the worker, image pull included. Default 600. |
| `BOXD_STATUS_TIMEOUT_SEC` | How long a status check waits. Default 15. |
| `BOXD_TEARDOWN_TIMEOUT_SEC` | How long stopping a worker waits for boxd to confirm the machine is gone. Default 30. |

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](https://docs.boxd.sh/guides/machine-specs.md) 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](https://docs.boxd.sh/guides/delete-after.md) 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](https://docs.agent-swarm.dev/docs/guides/runtime-pools#boxd-pools) covers pools, controllers, and push delivery in full.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.