Skip to content

Quickstart#

Get swarm running on your laptop, train an iris classifier, and inspect the audit trail — in ≈10 minutes. No LLM API key is required to boot; you'll need one (Anthropic or OpenAI) when you run your first pipeline.

Prerequisites#

  • Docker Desktop 4.25+ (or any OCI runtime — Podman works)
  • ≥8 GB RAM available to containers
  • A terminal
  • (For pipelines) an Anthropic API key or an OpenAI API key

1. Clone + start the stack#

git clone https://github.com/TheAiSingularity/swarm.git
cd swarm
cp .env.example .env     # edit to paste your API key
docker compose -f deploy/compose/docker-compose.yml up -d

Wait ~60 seconds for the first-time image pull + DB migration.

Verify:

curl -s http://localhost:8000/healthz | jq
# { "status": "ok", "version": "0.11.0", "db": "ready" }

open http://localhost:3000   # dashboard

Sign in with the seed admin:

  • email: admin@local
  • password: printed once in the api container logs (grep for SEEDED ADMIN)

2. Run your first pipeline#

From the dashboard: Pipelines → New.

  • Problem statement: Classify iris flowers by species.
  • Dataset: select iris.csv (pre-seeded)
  • Compliance profile: None (we'll cover RBI / HIPAA in later guides)
  • Template: fast_prototype
  • Click Run

Or from the CLI:

pip install --editable ml_team/           # one-time
swarm login --api http://localhost:8000 --email admin@local --password <seeded>
swarm pipelines run \
  --problem "Classify iris flowers by species" \
  --dataset iris.csv \
  --template fast_prototype

Watch it go. The dashboard streams agent messages, tool calls, and training logs live over WebSocket.

3. See the audit trail#

Every tool call, permission decision, and agent handoff lands in a SQL-queryable log.

  • Dashboard: Transparency → Denials
  • CLI: swarm pipelines status <run_id>
  • REST: curl http://localhost:8000/api/v1/permissions/denials?agent=algorithm_selector

4. Install a Claude Code plugin#

swarm's plugin loader accepts any CC-format plugin unchanged.

# Pull a real CC marketplace plugin
git clone https://github.com/obra/superpowers /tmp/superpowers

# Install
swarm plugins install /tmp/superpowers

# Verify — 14 skills + 1 hook + 3 commands + 1 agent all register
swarm plugins list

See How-to: Install a Claude Code plugin for the full matrix.

5. Stop + clean up#

docker compose -f deploy/compose/docker-compose.yml down -v

What's next#

Troubleshooting#

API container won't start

Run docker compose logs api | tail -50. Common causes:

  • Port 8000 in use (lsof -i :8000). Edit deploy/compose/docker-compose.yml to remap.
  • .env missing. cp .env.example .env.
  • Docker out of RAM. Allocate ≥8 GB in Docker Desktop → Settings → Resources.
Pipeline fails at the LLM-call step

Check ANTHROPIC_API_KEY (or OPENAI_API_KEY) in .env. Regenerate if suspicious — see SECURITY.md for our disclosure policy.

Dashboard shows 'Cannot reach API'

Ensure both api and dashboard containers are healthy (docker compose ps). If api is running but dashboard can't reach it, check your host's firewall or the NEXT_PUBLIC_API_URL variable in .env.