agent-swarm.dev is an open-source operating system for AI work. A lead agent delegates goals to workers such as Claude Code or Codex. Isolated containers, shared memory, tools, schedules, and review gates preserve work across sessions.
## What you get
- A lead agent that receives work from Slack, repositories, issue trackers, email, or the API
- [Schema-validated task results](./MCP.md#send-task) for callers that need structured JSON output
- [Deferred tasks](./MCP.md#defer-task) that wake when all or any watched tasks reach an outcome, or a deadline arrives
- [Inline tool-result images](https://docs.agent-swarm.dev/docs/ui#tool-result-images) in task logs, with previews that open at full size
- [Dashboard file attachments](https://docs.agent-swarm.dev/docs/ui#file-attachments) by paste, drag-and-drop, or file picker
- Workers in isolated Docker containers with development environments
- Memory and identity that persist across sessions, with citation ratings and self-rating hints enabled by default
- Workflows, schedules, scripts, and apps for recurring work
- [Extensions](https://docs.agent-swarm.dev/docs/guides/extensions) for trusted TypeScript hooks, installed as agent-owned inert drafts and activated by a trusted lead, operator, or dashboard user
- [Realtime rooms](./runbooks/realtime-rooms.md) for shared page state, presence, and live channels
- Your choice of harness and models: Claude Code, Codex, pi, opencode, [Cursor](https://docs.agent-swarm.dev/docs/guides/provider-auth/cursor), Amp, [Grok](https://docs.agent-swarm.dev/docs/guides/provider-auth/grok), Devin, or ACP agents
```mermaid
flowchart LR
subgraph IN["Tasks come in"]
direction TB
S["Slack"]
G["GitHub / GitLab"]
E["Email"]
A["API / CLI"]
end
LEAD(["Lead Agent plans & delegates"])
subgraph WORKERS["Workers in Docker"]
direction TB
W1["Worker"]
W2["Worker"]
W3["Worker"]
end
subgraph BRAIN["Persistent brain"]
direction TB
MEM["Memory (vector search)"]
ID["Identity (SOUL, CLAUDE.md)"]
end
subgraph OUT["Work ships"]
direction TB
PR["Pull Requests"]
REPLY["Slack replies"]
EMAIL["Email replies"]
end
IN --> LEAD --> WORKERS
WORKERS -->|reads context| BRAIN
WORKERS -->|writes learnings| BRAIN
WORKERS --> OUT
```
## Quick Start
Give your coding agent the operator skill for Docker Compose or Kubernetes:
```bash
npx skills add desplega-ai/agent-swarm
```
Or install it as a plugin in your harness:
| Harness | Command |
|---|---|
| Claude Code | `/plugin marketplace add desplega-ai/agent-swarm` then `/plugin install agent-swarm@agent-swarm` |
| Codex | `codex plugin marketplace add desplega-ai/agent-swarm && codex plugin add agent-swarm@agent-swarm` (or use `npx skills` above) |
| Cursor | `/add-plugin desplega-ai/agent-swarm` |
| Gemini CLI | `gemini extensions install https://github.com/desplega-ai/agent-swarm` |
| Antigravity / Factory Droid | `droid plugin marketplace add https://github.com/desplega-ai/agent-swarm` then `droid plugin install agent-swarm@agent-swarm` |
| OpenCode, pi, Devin, Kimi, others | `npx skills add desplega-ai/agent-swarm` |
The plugin's [privacy](https://www.agent-swarm.dev/privacy) and
[terms](https://www.agent-swarm.dev/terms) links describe the Agent Swarm website and
Cloud service. The self-hosted software remains covered by the [MIT License](./LICENSE).
Or self-host with the one-shot installer. It checks Docker and Compose v2, installs Bun when missing, runs `agent-swarm onboard --yes`, and prints the dashboard `/setup` link:
```bash
curl -fsSL https://raw.githubusercontent.com/desplega-ai/agent-swarm/main/install.sh | bash
```
Or use the examples directly:
```bash
git clone https://github.com/desplega-ai/agent-swarm.git && cd agent-swarm
cp .env.docker.example .env # Set API_KEY and the credential for your HARNESS_PROVIDER.
openssl rand -base64 32 > encryption_key
chmod 600 .env encryption_key
docker compose -f docker-compose.example.yml --env-file .env up -d
```
Agent ID variables are optional. Each container generates a UUID on first boot and keeps it in its personal volume, so identity survives restarts. Pin `*_AGENT_ID` in `.env` only to keep an existing identity or to survive removing volumes.
Read the [Compose checklist](./skills/agent-swarm/references/compose.md) before starting. API: http://localhost:3013, with `/docs` and `/openapi.json`.
Next, open the [dashboard](https://app.agent-swarm.dev) and connect it to your API with `API_KEY`. A new install lands on `/setup`, a guided first run that covers providers, agents, memory, integrations, and a first task.
Kubernetes: [install the OCI Helm chart](./charts/agent-swarm/README.md).
## Integrations
Slack · GitHub · GitLab · Azure DevOps · Linear · Jira · AgentMail · WhatsApp (Kapso) · Telegram, Teams and Discord ([Chat SDK](https://docs.agent-swarm.dev/docs/integrations/chat-sdk)) · Composio · Sentry · Devin · [Serply search](https://docs.agent-swarm.dev/docs/integrations/serply). [Integration guides](https://docs.agent-swarm.dev/docs/integrations).
AgentMail archives verified inbound deliveries before acknowledging them and retains the archive for 30 days, including mail excluded from task routing. See the [contact inbox triage runbook](runbooks/contact-inbox-triage.md) for retention, coverage limits, and rollout instructions.
## Learn more
- [Getting started](https://docs.agent-swarm.dev/docs/getting-started) · [Architecture](https://docs.agent-swarm.dev/docs/architecture/overview) · [Playbooks](https://docs.agent-swarm.dev/docs/playbooks) · [CLI](https://docs.agent-swarm.dev/docs/reference/cli) · [API reference](https://docs.agent-swarm.dev/docs/api-reference)
- [Orchestration patterns](./docs/orchestration-patterns.md) — Five patterns for delegating, fanning out, gating on humans, retrying, and persisting multi-step agent work
- [Agent templates](https://templates.agent-swarm.dev)
- [Public ranking](https://docs.agent-swarm.dev/docs/reference/telemetry#public-ranking): opt in with **Get ranked** (Settings → Configuration → Branding) to rank your install by tokens used on [agent-swarm.dev/ranking](https://agent-swarm.dev/ranking). It shows at the next hourly refresh. Token totals are public and exact; telemetry, the organization name and website must be set.
- Help: [contact@desplega.sh](mailto:contact@desplega.sh) · [Discord](https://discord.gg/KZgfyyDVZa)
## Contributing
Read [CONTRIBUTING.md](./CONTRIBUTING.md), fork the repository, create a branch, and open a PR. Discuss ideas on [Discord](https://discord.gg/KZgfyyDVZa).
> Are you an agent? Run `npx skills add desplega-ai/agent-swarm` or read the [operator skill](./skills/agent-swarm/SKILL.md).
## Star History
## License
[MIT](./LICENSE) · 2025-2026 [desplega.sh](https://desplega.sh)
### Feature defaults
Fresh deployments enable Slack thread renderer v2, queued Slack steering to the lead,
task steering, multi-runtime workers, RBAC, and task-tool preloading. Hybrid memory
search and graph expansion are also enabled. Explicit environment/config overrides
remain supported; see the [environment reference](https://docs.agent-swarm.dev/docs/reference/environment-variables).
When upgrading older workers, keep `MULTI_RUNTIME_ENABLED=false` until they support
runtime identities. Slack delegation rendering remains opt-in, and database retention
continues to default to dry-run.
