Agent Swarm operator skill
Agent Swarm
Agent Swarm is an operator skill that explains retaining workers’ personal volumes so their identities survive a restart.
- 1,012 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Deployment runs containers that can execute code and call external services
- Work integrations can expose repositories, messages and credentials
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add skills/agent-swarmDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Deployment runs containers that can execute code and call external services
- Work integrations can expose repositories, messages and credentials
This is third-party code. Review the repository files before installing.
What it does
Agent Swarm is an operator skill guiding an agent through preparation of a self-hosted AI worker team. It covers server selection, secrets and deployment checks. The platform receives tasks from a lead agent and passes them to workers through MCP. Deployment uses Docker Compose or Kubernetes. Users choose model providers and component resources before startup. A shared service stores tasks and team memory, while workflows and schedules define recurring work. The skill describes setup; servers and containers are deployed separately.
Who it is for. Agent-environment operations teams hosting lead agents and workers on their own infrastructure.
Good fit when
- A team prepares lead-and-worker deployment using its own provider accounts.
- Recurring tasks run on schedules with retained progress.
- Repositories and work channels feed requests into a shared queue.
- Container versions and persistent data are checked before an upgrade.
Not a fit when
- You need a single task in an existing agent without server infrastructure
- You cannot allocate an environment for agents, repositories and persistent data
- You expect installing the text skill to start an operational team automatically
Example request
Read the Agent Swarm operator skill and plan a small Compose test deployment. Show components, access and expected provider usage without starting containers.Limitations
A reference server needs about 4 vCPU, 8 GB of RAM and 40 GB of disk; agents need your credentials and model access. The one-shot installer exposes the API through a tunnel by default; inspect who can connect before starting it. Mount API storage at /app/data and retain the encryption key with the database for recovery. CAPABILITIES limits the MCP tool list but does not replace permission checks for REST API operations.
How to disable. Remove the installed skill from the agent's skills location. Stop the containers through the chosen deployment system. Preserve the database, encryption key and needed results before deleting volumes; removing instructions does not affect them.
FAQ
How do I add the instructions to Claude Code or Codex?
Run `npx skills add desplega-ai/agent-swarm` and select a supported client. Harness-specific plugins are an alternative. Open the operator skill in the agent after installation.
Does reading the skill require Docker?
No. Docker Compose v2 is required for one platform deployment route. Another route uses Kubernetes and Helm.
How is worker identity preserved?
Keep the worker’s personal volume. Its container writes an identifier there on first startup. Without that volume, the worker may receive a new identifier and lose recovery data for previous work.
How do I pin a deployment version?
Set `AGENT_SWARM_VERSION` to a published release in Compose and check the API and worker image tags. An empty value selects the mutable `latest` tag. Pin the chart version in Helm too.
Is a successful health response enough?
No. Also make an authenticated request to `/api/agents` and complete one test task. The API may respond while workers are unconfigured or unable to finish work.
What license does the platform use?
MIT.
Discussion
No questions or reviews yet.
Related
SkillsOne agent launches others in the background: Claude Code, Codex, Copilot CLI, Grok Build and Pi, with a model chosen per stage.
A layer over coding agents that assembles a temporary specialist team per task inside Claude Code, Codex, Cursor and Gemini
A team of AI agents from one request: it plans the task, writes code in parallel branches, tests, reviews and opens a pull request
Four skills for agents working with the Agent Kanban task board: worker, maintainer, task creator and project planner, with human review of the result
A self-hosted AgentOS for one workspace: plan-mode chat, private knowledge base, MCP tools, skills, memory and a sandbox
Ten AI agents in tmux panes: a manager hands tasks to seven workers, progress shows on a dashboard, with Claude Code, Codex, Cursor and OpenCode supported
README in short
The platform supports several agent harnesses and optional work-service integrations. Hosted cloud service terms are separate from self-hosted software. A source administration CLI also requires Bun 1.3.12 or later.
README badge
Original SKILL.md
--- name: agent-swarm description: Install, self-host, deploy, operate, or use agent-swarm. Covers Docker Compose, Kubernetes, configuration, coding agents, the admin UI, integrations, and connections. --- # Install and use agent-swarm The repository at `main` is the authority. Re-fetch referenced files before acting because this installed skill is a snapshot. Use the current examples when commands or options change. Mark completed checklist items. Record skipped optional items and the reason. ## Install - [ ] **Required: establish the target.** Confirm the host, Compose or Kubernetes, harness, credentials, agent count, and private or public access. Default to every agent in the [Compose example](https://github.com/desplega-ai/agent-swarm/blob/main/docker-compose.example.yml), the reference deployment (1 lead and 11 workers); trim only when the operator has a reason. These choices determine resources and networking. Read the [deployment guide](https://docs.agent-swarm.dev/docs/guides/deployment). - [ ] **Required: check prerequisites.** Compose needs Git, Docker with Compose v2, OpenSSL, curl, and jq. Kubernetes needs kubectl, Helm, and persistent storage. Confirm capacity for the selected workers. Read the [Compose example](https://github.com/desplega-ai/agent-swarm/blob/main/docker-compose.example.yml) and [chart values](https://github.com/desplega-ai/agent-swarm/blob/main/charts/agent-swarm/values.yaml). - [ ] **Required: assign component minimums.** Keep `.env` minimal: boot identity, authentication, encryption, URLs, and harness credentials. Set supported non-boot values through swarm config so the system can validate and reload them. Apply all three tiers in [component minimums](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/components.md). - [ ] **Required: protect secrets and persistent data.** Generate an API key and preserve the encryption key with the database. Each agent needs its own personal volume, which holds the UUID it generates on first boot. The volume preserves identity and task recovery; the encryption key preserves encrypted credentials. Read [secrets encryption](https://docs.agent-swarm.dev/docs/guides/secrets-encryption) and [component minimums](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/components.md). - [ ] **Required, choose one: Compose.** Clone the repository, copy `.env.docker.example`, set `API_KEY` and harness credentials (agent IDs are optional), then start the example services. The examples define the actual environment and volumes. Execute the [Compose procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/compose.md). - [ ] **Required, choose one: Kubernetes.** Create the credential Secret and install `oci://ghcr.io/desplega-ai/charts/agent-swarm`. Pin the release with `--version`; omitting it takes the newest published chart. The image tag follows the chart `appVersion`, so the chart version is the pin. Use pool replicas to size workers. Execute the [Helm procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/helm.md). Follow [Kubernetes and Helm](https://github.com/desplega-ai/agent-swarm/blob/main/docs-site/content/docs/%28documentation%29/guides/kubernetes.mdx) for ingress, dashboard connection, and CORS. - [ ] **Required: mount the API volume at `/app/data`, never `/app`.** A named volume shadows the image path it covers, so an `/app` mount freezes the image's `migrations/` and `package.json` at install time while the binary upgrades. The API then queries schema no migration created, and `/health` reports the stale version and stays green. Existing installs need a one-time data move. Execute the [pinning and upgrade procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/upgrade.md). - [ ] **Required: pin the image version.** On Compose, set `AGENT_SWARM_VERSION` in `.env` to a published release and confirm the API and every agent resolve the same tag. Blank means `latest`, which moves on every commit to `main` and is not a release; with `pull_policy: always` an unpinned stack can change version on any restart. Pinning and the `/app/data` mount are complementary; pinning alone does not make upgrades safe. Execute the [pinning and upgrade procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/upgrade.md). - [ ] **Required: verify operation.** Check `/health`, authenticated `/api/agents`, and a completed task. A healthy API alone does not prove workers can execute tasks. Execute the [API verification procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/usage.md). - [ ] **Optional: co-deploy agent-fs.** Enable shared files, attachments, and search when agents need durable file exchange. Compose includes agent-fs and MinIO. Helm enables it through `agentFs.enabled`. Read [agent-fs deployment](https://docs.agent-swarm.dev/docs/guides/agent-fs-co-deployment) and its [minimums and omission procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/components.md). - [ ] **Optional: select another harness.** Choose Codex, pi with OpenRouter, or Bedrock when your credentials or models require it. Read [harness configuration](https://docs.agent-swarm.dev/docs/guides/harness-configuration) and the [credential minimums](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/components.md). - [ ] **Recommended: add HTTPS.** The hosted dashboard, OAuth callbacks, and webhooks need a public HTTPS API origin. Compose ships a Caddy `tls` profile; the chart has a cert-manager shortcut. Execute the [HTTPS procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/https.md). - [ ] **Optional: use another deployment manager.** Use the [deployment guide](https://docs.agent-swarm.dev/docs/guides/deployment) for VPS proxies, Dokploy, and Coolify. Use [DEPLOYMENT.md](https://github.com/desplega-ai/agent-swarm/blob/main/DEPLOYMENT.md) for systemd. The onboarding wizard is an alternative described in [getting started](https://docs.agent-swarm.dev/docs/getting-started). - [ ] **Required before any upgrade: back up the database and encryption key.** Migrations are forward-only, so re-pinning to an older tag is not a rollback. The backup is. Execute the [upgrade procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/upgrade.md) on Compose, or the [Kubernetes operations procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/operate-k8s.md) on Helm. - [ ] **Recommended on Kubernetes: learn day-2 operations.** Upgrades, scaling pools, credential rotation, backups, and the troubleshooting table live in the [Kubernetes operations procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/operate-k8s.md). - [ ] **Optional: add backups and telemetry.** Backups support recovery. OpenTelemetry exposes service activity. Read [chart backup settings](https://github.com/desplega-ai/agent-swarm/blob/main/charts/agent-swarm/README.md) and [OpenTelemetry](https://docs.agent-swarm.dev/docs/guides/observability-opentelemetry). ## Use, in this order - [ ] **Required: access the API through HTTP and MCP.** HTTP exposes `/docs` and `/openapi.json` on port 3013. MCP uses `/mcp`. Connect your coding agent with `bunx @desplega.ai/agent-swarm connect`. This gives your project access to the swarm. Follow the [API and coding-agent procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/usage.md). - [ ] **Optional: connect the admin UI.** Point `https://app.agent-swarm.dev` at your API, or run `apps/ui` locally. Use it to inspect tasks, manage agents, and configure the deployment. Read the [UI guide](https://docs.agent-swarm.dev/docs/ui) and [local UI commands](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/usage.md). - [ ] **Optional: enable Slack first.** Slack provides native task intake, replies, and steering. Import `slack-manifest.json`, create both tokens, configure the API, and send the bot a DM. Execute the [Slack procedure](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/slack.md). - [ ] **Optional: enable GitHub or GitLab.** Connect repository events so agents can respond to development work. Read [GitHub](https://docs.agent-swarm.dev/docs/integrations/github), [GitLab](https://docs.agent-swarm.dev/docs/integrations/gitlab), and the [integration minimums](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/components.md). - [ ] **Optional: enable other integrations.** Add the systems that supply your work. Read [Linear](https://docs.agent-swarm.dev/docs/integrations/linear), [Jira](https://docs.agent-swarm.dev/docs/integrations/jira), [AgentMail](https://docs.agent-swarm.dev/docs/integrations/agentmail), [Kapso](https://docs.agent-swarm.dev/docs/integrations/kapso), and [Sentry](https://docs.agent-swarm.dev/docs/integrations/sentry). Apply their [minimums](https://github.com/desplega-ai/agent-swarm/blob/main/skills/agent-swarm/references/components.md). - [ ] **Optional: add connections.** Register OpenAPI, GraphQL, or MCP services to give scripts typed access to external systems. Configure connections through the lead or Settings → Connections. Read [script connections](https://docs.agent-swarm.dev/docs/guides/script-connections). Use [Composio](https://docs.agent-swarm.dev/docs/integrations/composio) through the `x` router for additional integrations. - [ ] **Optional: go deeper.** Use durable capabilities when recurring work needs context or automation. Read [memory](https://docs.agent-swarm.dev/docs/architecture/memory), [workflows](https://docs.agent-swarm.dev/docs/concepts/workflows), [schedules](https://docs.agent-swarm.dev/docs/concepts/scheduling), [scripts](https://docs.agent-swarm.dev/docs/guides/scripts-runtime), [apps](https://docs.agent-swarm.dev/docs/apps), and [worker skills](https://github.com/desplega-ai/agent-swarm/blob/main/runbooks/skills.md).