Agent Swarm

---
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. 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, jq, and a UUID generator. 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 a stable UUID and its own personal volume. This preserves identity, task recovery, and 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`, configure credentials and UUIDs, 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).