agent-swarm: a self-hosted lead-agent harness for teams that already live in Slack
Your Company Agentic Operating System
At a glance
- What is it?
- desplega-ai/agent-swarm is an MIT-licensed TypeScript orchestration layer that puts a lead agent in front of Docker-isolated coding workers with a persistent memory store. The design is opinionated toward inbound work arriving from chat and issue trackers, and the setup cost is paid up front in environment variables and UUIDs.
- Who is it for?
- Adopt agent-swarm if you want a self-hosted lead agent that turns Slack, GitHub, GitLab, Linear or Jira traffic into containerized coding work with memory that survives the session. Do not adopt it if you only need one agent in one terminal, or if you cannot operate Docker Compose or a Helm release and keep an encryption key safe.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository received new commits within the last day.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem agent-swarm picks: work that arrives as conversation, not as a task
Most coding-agent tooling assumes a human sits at a terminal and types a request. agent-swarm assumes the opposite. The README lists Slack, GitHub/GitLab, email and an API/CLI as the entry points, and the flow diagram routes all of them into a single lead agent that plans and delegates. That reframes the unit of work: instead of one prompt and one session, you get a queue of inbound messages that have to be triaged, split into tasks, and handed to somebody or something that can finish them.
The intended user is a company that wants an internal agent layer rather than a personal assistant. The topics list includes human-in-the-loop, self-hosted and agent-teams, and the tagline is an engine to make your company AI Native. That is a statement about organizational plumbing. The value proposition is continuity: the README says isolated containers, shared memory, tools, schedules and review gates preserve work across sessions. If your agents forget everything between runs, an inbound Slack message becomes a fresh conversation every time, and the same context gets re-explained. agent-swarm's answer is a persistent brain that workers read from and write learnings back into.
It is not a model and not an IDE plugin. It is the layer that decides which agent handles what, in which container, with which memory, and where the result gets posted back. That layer is the product.
Lead agent, Docker workers, and a memory store that workers both read and write
The architecture diagram in the README is short enough to read literally. Tasks arrive from four sources. A lead agent plans and delegates. Workers run in Docker. A persistent brain holds memory, described as vector search, plus identity files named SOUL and CLAUDE.md. Output ships as pull requests, Slack replies or email replies.
The interesting edge in that diagram is bidirectional. Workers read context from the brain and write learnings back to it. That means the memory store is not a static knowledge base you seed once; it accumulates from execution. The identity side is file-based, which is a deliberate choice: SOUL and CLAUDE.md are plain files, so an agent's persona and instructions can be versioned and diffed like any other repository artifact rather than living in a database row.
Worker isolation is stated as Docker containers with development environments. The README does not describe how resource limits, network policy or image contents are configured, so treat those as things to check in the Compose checklist and the Kubernetes chart README rather than as documented guarantees. What is documented is the harness choice: Claude Code, Codex, pi, opencode, Devin or ACP agents. That is a genuinely useful separation. The orchestration layer does not force a model vendor, and swapping harnesses does not require rewriting the delegation logic.
The lead agent's own planner is the least specified piece in the material. The diagram says it plans and delegates; the README does not say whether planning is a single LLM call, a scripted workflow, or something you configure per integration. Anyone evaluating this should read the architecture overview at docs.agent-swarm.dev/docs/architecture/overview before assuming a particular behavior.
Getting it running: eight UUIDs, one encryption key, one compose file
There are two documented paths. The first is aimed at coding agents rather than people: npx skills add desplega-ai/agent-swarm installs an operator skill for Docker Compose or Kubernetes. The README even addresses agents directly at the bottom, telling them to run that command or read skills/agent-swarm/SKILL.md. If you are the kind of team that lets an agent bootstrap its own infrastructure, that is the intended entry.
The second path is manual and more revealing about the real cost:
git clone https://github.com/desplega-ai/agent-swarm.git && cd agent-swarm cp .env.docker.example .env openssl rand -base64 32 > encryption_key chmod 600 .env encryption_key docker compose -f docker-compose.example.yml --env-file .env up -d
The comment on the cp line is the important part. You must set API_KEY, a harness credential, and all eight agent UUIDs. Eight is a specific number, and it implies a fixed roster of agent roles baked into the example environment rather than a dynamic pool. The README does not enumerate those eight roles, so the .env.docker.example file is where you find out what you are actually configuring.
The encryption_key file is generated separately from .env and locked to owner-only permissions. That suggests it protects stored secrets or memory at rest, though the README does not say which. Either way it is a file you now own and must not lose, because it is not derived from anything else in the setup.
The API listens on http://localhost:3013 and exposes /docs and /openapi.json, so you can inspect the surface before writing any integration. The hosted dashboard at app.agent-swarm.dev is connected to your API rather than being the source of truth, which keeps the deployment self-hosted. For Kubernetes, the README points at an OCI Helm chart under charts/agent-swarm/README.md. Before starting either path, the README explicitly says to read the Compose checklist at skills/agent-swarm/references/compose.md.
What the daily-release cadence costs you in upgrades
The release list shows v1.142.0, v1.143.0 and v1.144.0 on three consecutive days. The README states plainly that the repo evolves every single day. That is not a marketing line so much as a maintenance warning. A project releasing at that rate has a moving API surface, and the /openapi.json endpoint is your practical defense: pin the version you deploy, and diff the OpenAPI document between releases before upgrading rather than reading changelogs.
The Compose and Helm paths also carry different upgrade burdens. With Compose you control the image tag and can roll back by editing one line in docker-compose.example.yml. With the Helm chart the release mechanism handles rollout, but you inherit whatever the chart's values schema expects, and a chart bump can change required keys without touching your application code. Neither path is described in the README as having a migration story for the memory store, which is the thing that actually holds accumulated state. If vector memory lives in a volume, back that volume up before any upgrade; if it lives in a database you provisioned, the backup is yours to schedule. The README does not settle which it is.
Licensing is straightforward. MIT, copyright 2025-2026 desplega.sh, with the LICENSE file at the repository root. MIT permits commercial use, modification and redistribution provided the copyright notice and permission notice are retained. That is the whole of it; nothing in the material suggests a separate enterprise tier or a source-available carve-out, and this is not legal advice.
Where agent-swarm is the wrong tool
The setup path names its own prerequisites. You need Docker Compose or Kubernetes, an API key, a harness credential, eight agent UUIDs, and a generated encryption key you keep at chmod 600. That is a real operational surface. A single developer who wants an agent to refactor a module in their working copy gets nothing from a lead agent, a worker pool, or a vector memory store. The same result comes from running the harness directly. The orchestration is overhead until you have concurrent inbound work and more than one person reading the output.
There is a second, subtler mismatch. agent-swarm is built around inbound channels: Slack, GitHub/GitLab, email, API. If your work originates in a tracker the integration list does not cover, or in a bespoke internal system, you are writing against the API rather than using a supported path. The README lists Slack, GitHub, GitLab, Linear, Jira, AgentMail, WhatsApp via Kapso, Composio, Sentry and Devin. Anything outside that list is integration work you own.
The most honest limitation is documentation depth at the edges. The README gives a diagram, a quick start, and links outward. It does not describe failure handling when a worker container dies mid-task, how the lead agent behaves when two inbound messages conflict, or what happens to in-flight work during an upgrade. Given a release cadence of roughly one per day, some of those answers are likely to change faster than they are written down. Budget for reading the source, not just the docs.
How it differs from a single-harness agent runner
The nearest comparison is a plain agent runner such as Claude Code or Codex used directly, which is what agent-swarm actually delegates to. The difference is not capability but placement. A direct harness invocation is stateless with respect to your organization: it starts when you type, ends when you close the terminal, and remembers only what its own context window or local files hold. agent-swarm inserts three things between the request and the harness. A lead agent that decides who does the work. A container boundary that keeps each worker's filesystem separate. A shared brain that outlives the session and is written to by the workers themselves.
That third piece is the real divergence. A runner's memory is a file you maintain. agent-swarm's memory is described as vector search, read and written by workers, which makes it a system you operate: it grows, it can be queried, and it can also accumulate stale or wrong entries that later workers treat as context. There is no described review gate on what gets written to memory, only review gates on work output. That asymmetry is worth naming. If you care about the quality of accumulated context, you need a way to inspect and prune the store, and the README does not describe one.
The harness-agnostic layer is the other difference. Because agent-swarm supports Claude Code, Codex, pi, opencode, Devin and ACP agents behind one orchestration API, you can change the underlying model without changing how Slack messages become pull requests. A direct runner ties you to one vendor's loop. That flexibility is the reason to accept the extra moving parts, and if you do not need it, you do not need agent-swarm.
Who should deploy this, and what to confirm before you do
Deploy it if you have a team already routing work through Slack, GitHub or an issue tracker, you are willing to run Docker Compose or a Helm release, and you want agent output to accumulate rather than reset. The persistent brain plus the review gates is the combination that makes an agent layer usable by more than its author. The harness-agnostic design means you are not betting on one vendor's coding loop.
Do not deploy it if your agent usage is one person, one terminal, one repository. The eight agent UUIDs, the separate encryption key, and the container fleet are all cost with no return at that scale. Do not deploy it either if you cannot commit to owning the memory store, because that is the component that carries state across sessions and the README does not describe how it is backed up or migrated.
Before starting, read skills/agent-swarm/references/compose.md, as the README instructs, and open .env.docker.example to see what the eight UUIDs correspond to. Then confirm three things in the docs: the lead agent's planning behavior, the storage backing for vector memory, and whether your harness credential is reachable from inside the worker container. Bring the API up on port 3013 and read /openapi.json to see the actual surface you will be integrating against. That document, not the README, is the contract.
Editorial conclusion
Adopt agent-swarm if you want a self-hosted lead agent that turns Slack, GitHub, GitLab, Linear or Jira traffic into containerized coding work with memory that survives the session. Do not adopt it if you only need one agent in one terminal, or if you cannot operate Docker Compose or a Helm release and keep an encryption key safe. Before committing, verify three things against docs.agent-swarm.dev: what the lead agent's planner actually does with an incoming Slack thread, where the vector memory is stored and how it is backed up, and whether your chosen harness credential works inside the worker image. The eight agent UUIDs in .env.docker.example are the first thing to get right, because the clone-and-compose path fails without them.
Community notes