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. 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).