Skip to main content

Operations runbook — Local setup

This walks a brand-new developer from git clone to a running local AlphaSwarm stack.

For a personal or limited-scope environment that connects local services to the hosted platform, start with the recommended alphaswarm-cli local dev lifecycle. That runbook covers the personal-hosted-link profile, Compose orchestration, hosted-link/device tunnel connection, status, logs, and shutdown.

This page remains useful for legacy/lower-level setup context: editable installs, local config generation, direct Compose, Terraform/k3d, and admin overlay workflows.

Prerequisites​

ToolMin versionUsed for
Python3.11AlphaSwarm runtime + the new alphaswarm_core + alphaswarm_controller packages
Node.js20Vite + legacy webui builds
pnpm9Frontend dep management (corepack enable && corepack prepare [email protected] --activate)
Docker25+Local compose stack + image builds
docker buildx0.13+Multi-arch image builds
Terraform1.10+Provisioning-only (rule 42)
k3d5.7+Local k3s cluster (for the Terraform-driven path)
kubectl1.30+Workload introspection

Step 1 — clone + install editable​

git clone https://github.com/Alpha-Swarm-ai/alphaswarm.git
cd alphaswarm

python -m pip install -e .
python -m pip install -e ./alphaswarm_core[dev]
python -m pip install -e ./alphaswarm_controller[dev,all-providers]
pnpm --dir alphaswarm_client install

Step 2 — generate .env.local​

make generate-config ENV=local

This reads alphaswarm_platform/deployments/compose/.env.schema and writes alphaswarm_platform/deployments/compose/.env.local. Open the file and fill in the <set-via-secret-store> placeholders for any service you plan to use.

Step 3 — bring up the stack (two options)​

For the hosted-link local dev path, prefer:

alphaswarm-cli local dev plan
alphaswarm-cli local dev init
alphaswarm-cli local dev build
alphaswarm-cli local dev up
alphaswarm-cli local dev connect --code <pairing-code>   # --code is required
alphaswarm-cli local dev status
alphaswarm-cli local dev logs
alphaswarm-cli local dev down

The lower-level options below are still valid when you need to work directly on the local package, compose files, or Terraform/k3d deployment path.

Option A — Docker Compose (new path, Phase 3 refactor)​

make dev

This brings up:

  • alphaswarm-postgres (pgvector)
  • redis-stack
  • alphaswarm-core (FastAPI)
  • alphaswarm-worker (Celery)
  • alphaswarm-ml-control-worker
  • alphaswarm-executor
  • alphaswarm-mcp
  • alphaswarm-client (unified gateway, port 3000)

Once everything is Up (healthy):

Option B — Terraform + k3d (canonical, hard rule 42)​

alphaswarm-cli deploy build      # build + push images to the local registry
alphaswarm-cli deploy up         # terraform apply -> k3d cluster + workloads
alphaswarm-cli deploy status     # pod + service rollup
alphaswarm-cli deploy logs api   # tail alphaswarm-api logs

alphaswarm-cli deploy * is the existing path that lands every state mutation in terraform_runs. The Docker Compose path is friendlier for fast iteration but doesn't update the ledger.

Step 4 — bring up the admin overlay (optional)​

The alphaswarm_controller micro-project runs on a separate Docker network (alphaswarm-admin) so it's isolated from the workloads it manages.

make dev-admin

After that, curl http://localhost:9000/manage/health should return {"status": "ok", ...}.

Step 5 — verify​

make test                # all tests
make test-platform-core  # alphaswarm_core only
make test-providers      # alphaswarm_controller provider contract tests

Troubleshooting​

SymptomFix
make generate-config ENV=local errors with missing required fieldsThe schema parser caught a malformed block in .env.schema. Open the file, look for the entry above the error line, ensure every block has key: / description: / required: / targets: / classification:.
docker compose up fails with port already in useThe Vite dev server publishes 3001 by default; the compose stack publishes 3000. Stop whichever is running first or override via docker-compose.override.yml.
pnpm --dir alphaswarm_client build runs out of memoryNODE_OPTIONS=--max-old-space-size=4096 pnpm --dir alphaswarm_client build.
alphaswarm-cli deploy up fails with terraform binary not foundchoco install terraform (Windows) or set ALPHASWARM_TERRAFORM_BINARY=/path/to/terraform.
alphaswarm_controller shows auth_enabled: false in /manage/healthSet ALPHASWARM_AUTH_OIDC_ISSUER=https://your-tenant.us.auth0.com/ in .env.local (plus whatever else auth_required/use_central_auth need), restart alphaswarm-cp.