--- 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`. Omit `--version` for latest, or pin a chosen release. 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: 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). - [ ] **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).