Install Agent Swarm, configure your first lead and worker agents, and run your first multi-agent task in minutes

This guide walks you through setting up a fully operational Agent Swarm with a lead agent and workers.

Agent Swarm supports multiple AI providers via the harness system. The default is Claude Code (recommended), but you can also use pi-mono for access to other model backends. See the Harness Configuration guide for details.

Prerequisites

Docker and Docker Compose
Claude Code installed, with an OAuth token (claude setup-token) — or an API key for an alternative provider

Agent Swarm ships with official templates that give your agents pre-configured identities, skills, and setup scripts. Instead of starting from scratch, pick a template that matches the role you need.

Template	Role	Best for
Lead	`lead`	Orchestrating workers, decomposing tasks, coordinating projects
Coder	`worker`	Implementation, PRs, code reviews
Researcher	`worker`	Web research, analysis, documentation
Reviewer	`worker`	Code review, quality assurance
Tester	`worker`	Testing, validation, CI/CD
Forward Deployed Engineer	`worker`	Client-facing work, rapid prototyping

To use a template, set the TEMPLATE_ID environment variable when starting an agent:

# Use the coder template for a worker
TEMPLATE_ID=official/coder docker compose up worker-1 -d

# Use the lead template
TEMPLATE_ID=official/lead docker compose up lead -d

Templates are fetched from the Templates Registry and cached locally for 24 hours. You can also create your own templates and contribute them to the community.

Browse all available templates at templates.agent-swarm.dev.

Option A: Onboard Wizard (Recommended)

The fastest way to get a full swarm running. The interactive wizard collects credentials, generates docker-compose.yml + .env, starts the stack, and verifies health.

bunx @desplega.ai/agent-swarm onboard

Or in non-interactive mode with a preset:

ANTHROPIC_API_KEY=sk-... bunx @desplega.ai/agent-swarm onboard --yes --preset=dev

Available presets: dev, content, research, solo. Use --dry-run to preview without writing files.

Option B: Manual Docker Compose

Set up manually with Docker Compose for full control.

git clone https://github.com/desplega-ai/agent-swarm.git
cd agent-swarm

# Configure environment
cp .env.docker.example .env
# Edit .env — set API_KEY and CLAUDE_CODE_OAUTH_TOKEN at minimum
# Optionally set TEMPLATE_ID=official/coder for workers, TEMPLATE_ID=official/lead for leads

# Start everything
docker compose -f docker-compose.example.yml --env-file .env up -d

The API runs on port 3013. The dashboard is available separately (see the Dashboard UI section).

Option C: Local API + Docker Workers

Run the API locally and connect Docker workers to it.

git clone https://github.com/desplega-ai/agent-swarm.git
cd agent-swarm
bun install

# 1. Configure and start the API server
cp .env.example .env
# Edit .env — set API_KEY
bun run start:http

In a new terminal, start a worker:

# 2. Configure and run a Docker worker
cp .env.docker.example .env.docker
# Edit .env.docker — set API_KEY (same as above) and CLAUDE_CODE_OAUTH_TOKEN
bun run docker:build:worker
mkdir -p ./logs ./work/shared ./work/worker-1
bun run docker:run:worker

Option D: Claude Code as Lead Agent

Use Claude Code directly as the lead agent — no Docker required for the lead.

# After starting the API server (Option C, step 1):
bunx @desplega.ai/agent-swarm connect

This configures Claude Code to connect to the swarm. Start Claude Code and tell it:

Register yourself as the lead agent in the agent-swarm.

Verifying Your Setup

Once your swarm is running, you can verify it's working:

Check the API — Visit http://localhost:3013/health
Check agents — Use the dashboard or API to see registered agents
Send a test task — Message the lead agent via Slack or the API

Configuration

Required Environment Variables

Variable	Description
`API_KEY`	Secret key for API authentication
`CLAUDE_CODE_OAUTH_TOKEN`	OAuth token for Claude CLI (default provider)

Credential requirements depend on your chosen harness provider. See Harness Configuration for alternatives like ANTHROPIC_API_KEY or OPENROUTER_API_KEY.

Optional Variables

Variable	Default	Description
`PORT`	`3013`	API server port
`HARNESS_PROVIDER`	`claude`	AI provider: `claude` or `pi`. See Harness Configuration
`AGENT_ID`	Auto-generated	Stable UUID for task resume
`AGENT_NAME`	Auto-generated	Display name for the agent
`AGENT_ROLE`	`worker`	Role: `worker` or `lead`
`MCP_BASE_URL`	`http://host.docker.internal:3013`	MCP server URL

For the complete list, see Environment Variables.

Next Steps

Harness Configuration — Configure Claude Code, pi-mono, or a mixed swarm
Browse Templates — Explore and preview agent templates
Architecture Overview — Understand the system design
Task Lifecycle — Learn how tasks flow through the swarm
Deployment Guide — Production deployment options
AgentMail Integration — Give agents their own email inboxes
Linear Integration — Bidirectional ticket tracking with Linear
Contributing — Learn how to contribute code, templates, and docs

Getting Started