/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, 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: