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 m

Preview of the first 4,000 characters. Read full instructions →

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.