agent-swarm

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, 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.
• 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 and chart values.
• 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.
• 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 and component minimums.
• 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.
• 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. Follow Kubernetes and Helm 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.
• 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.
• 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.
• 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 and its minimums and omission procedure.
• Optional: select another harness. Choose Codex, pi with OpenRouter, or Bedrock when your credentials or models require it. Read harness configuration and the credential minimums.
• 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.
• Optional: use another deployment manager. Use the deployment guide for VPS proxies, Dokploy, and Coolify. Use DEPLOYMENT.md for systemd. The onboarding wizard is an alternative described in 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 on Compose, or the Kubernetes operations procedure 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.
• Optional: add backups and telemetry. Backups support recovery. OpenTelemetry exposes service activity. Read chart backup settings and 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.
• 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 and local UI commands.
• 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.
• Optional: enable GitHub or GitLab. Connect repository events so agents can respond to development work. Read GitHub, GitLab, and the integration minimums.
• Optional: enable other integrations. Add the systems that supply your work. Read Linear, Jira, AgentMail, Kapso, and Sentry. Apply their minimums.
• 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. Use Composio through the x router for additional integrations.
• Optional: go deeper. Use durable capabilities when recurring work needs context or automation. Read memory, workflows, schedules, scripts, apps, and worker skills.