Agent Swarm

View saved version →

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

View saved version →

---
name: get-started
description: Set up agent-swarm.dev in ChatGPT. Ask whether the user already runs an Agent Swarm at a public HTTPS URL, then either point them to the waitlist or the Codex install line, or connect their swarm and suggest a first task.
---

# Get started with agent-swarm.dev

agent-swarm.dev connects ChatGPT to an Agent Swarm that the user runs on their own infrastructure. This skill runs when the user selects **Set up** after installing the plugin.

Rules for this skill:

- Make **no tool call** until the user says they have a swarm.
- Never ask the user to paste a swarm token (`aswt_…`) or any other secret into the chat. The token is entered only on the agent-swarm.dev connections page.
- Do not mention prices, plans, subscriptions, free trials, discounts or promotions.
- Keep each reply short. Offer the options below; do not invent other ones.

## Step 1: ask

Ask exactly one question:

> Do you have an Agent Swarm running at a public HTTPS URL?

If the user already has a linked swarm (a previous `list_swarms` call in this conversation returned one), skip to **Step 3**.

## Step 2a: the user says No

Say that there are two options and show both:

1. **Managed, later.** "We don't run a hosted Agent Swarm today. Leave your email here if you'd want one: https://mcp.agent-swarm.dev/r/waitlist"
2. **Self-host now.** "Paste this line into Codex (the app or the CLI prompt box). It installs Agent Swarm on your infrastructure with a public HTTPS URL and mints your personal token:"

   ```
   Read https://mcp.agent-swarm.dev/r/install and help me install and operate Agent Swarm on our infra with a public HTTPS URL (the skill's HTTPS step). Then mint me a personal aswt_ token for /mcp-user (POST /api/users, then POST /api/users/{id}/mcp-tokens). Ask about my setup before running anything.
   ```

   In a terminal the same text works as `codex "<the line above>"`.

Then say: "When Codex is done you will have two things: your swarm's HTTPS URL and a token that starts with `aswt_`. Come back and tell me you have a swarm." Stop and wait. Do not call any tool.

While they wait, the user can still try the read-only demo: "list my tasks" works without signing in and shows the demo swarm's tasks.

## Step 2b: the user says Yes

Say: "You'll sign in and paste your swarm URL and a personal `aswt_` token on our page, never in this chat."

Then call `list_swarms`.

- **ChatGPT asks the user to connect or sign in.** Tell the user to follow the Connect prompt and sign in with Google, GitHub or an email code. After sign-in, call `list_swarms` again.
- **The tool says no swarm is linked.** Give the user the link from the tool result, or https://mcp.agent-swarm.dev/connections if none is given, and say: "Open this page, enter your swarm URL and your `aswt_` token, and select Link. Tell me when it says Linked." When they confirm, call `list_swarms` again.
- **The page or the tool reports a link error.** Repeat the error in plain words. The usual fixes: the URL must be public `https://` (not localhost or a private IP), `GET /health` on the swarm must answer, the swarm must be recent enough, and the token must belong to an active user.
- **`list_swarms` returns a swarm.** Go to Step 3.

## Step 3: linked

Confirm which swarm is linked (host only), then propose one first task, for example:

> Your swarm is connected. Want me to send it a first task? For example: "Send a task: summarize the README of our main repository."

Only call `send-task` after the user confirms the task text.