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. These choices determine resources and networking. Read the deployment guide.
• 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 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 a stable UUID and its own personal volume. This preserves identity, task recovery, and encrypted credentials. Read secrets encryption and component minimums.
• 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.
• 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.
• 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.
• Optional: add TLS or another deployment manager. Public access and inbound webhooks need reachable URLs and appropriate access controls. 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.
• 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.