agent-swarm: a multi-agent swarm operating system as MCP — understand the full deployment cost before you start

Who it's for

• For teams or individuals who want to orchestrate multiple agents within a unified system: you direct and monitor a fleet of agents through task lifecycle tools (send-task, cancel-task, task-action, poll-task, store-progress), steering messages, session/session logs, and budget management (getBudget/getBudgets/upsertBudget/deleteBudget). The latest version is v2.7.7.
• Its e2e contract covers "every route, MCP tool, and workflow node type," and the domains document 32+ MCP tools — a good fit for users treating multi-agent collaboration as long-term infrastructure.
• Not for users who want zero-deployment, single-file usage: the main installation path is a preset full deployment with a tunnel, and the Compose stack includes lead, workers, agent-fs, MinIO, and Caddy. With the tls profile, it also deploys to real agent-swarm.dev subdomains.
• Credential requirements, authentication methods, and the default threshold of the budget gate are not stated in the collected evidence; check the official README/documentation before use.

First attempt in 3 minutes

• The official main path is the full installation described in the README and docs: ui-install.sh --preset full --tunnel.
• Prerequisites: a host that allows spinning up multiple service containers, with the Bun runtime installed (agent-swarm is built on Bun, with bun:sqlite as the data layer); the quality gates use bun run lint and tsc:check, which indicates the source can be verified with Bun workflows.
• Side-effect warning: this is a real deployment, not a read-only trial. It writes local state (SQLite), spins up services such as MinIO/Caddy, and with the tls profile occupies real subdomains. Confirm these side effects are acceptable before running; the evidence provides no official rollback/undo commands, so don't assume a one-click restore.
• Success signal: once the install script finishes, lead, workers, agent-fs, MinIO, and Caddy in the Compose stack are running, and you can walk through system status via the dashboard UI (the official demo uses agent-browser).
• If you only want to explore the tool surface without deploying, the evidence offers no lighter official path — don't guess at alternative installation methods.

Use cases

• Case 1: dispatch and track a task. After deployment, call send-task via MCP to send a task to the swarm, then use poll-task to poll progress and store-progress to record it (the terminal 'skipped' status is supported); use cancel-task to abort when needed. Expected result: the task's lifecycle from creation to terminal state is traceable in the session logs.
• Case 2: set a daily budget to prevent runaway spending. Call getBudget/getBudgets to view current budgets and use upsertBudget to set a daily spend cap; the official evidence states that when spending hits the daily gate, the system rejects subsequent tasks — a direct way to observe the budget mechanism in action. Use deleteBudget to remove one.

Usage boundaries

• Read/write nature: there are read-only queries (getBudgets, poll-task, session logs) as well as write and cancel operations (send-task, upsertBudget, cancel-task); before any write operation after your first attempt, confirm the target state in the dashboard.
• Local data: the data layer is bun:sqlite, which writes local database state on the host; this is a local write and does not become read-only just because query tools exist.
• Deployment side effects: it spins up a multi-service stack in one go and may occupy real domains; the evidence gives no rollback path.
• Not yet confirmed: the default value of the daily budget gate, credential and authentication requirements, and the full parameter signatures of each MCP tool (only the tool names and the 32+ count are confirmed). Defer to the official README/documentation before use.