Skip to main content

Quickstart

Target: a sibling-repo workspace checkout to a green backtest result in under 30 seconds of typing (plus first-time Docker image pull, which is unavoidable).

Current shipped deployment version: 0.1.0-alpha.1. Compose and Kubernetes artifacts label workloads with that string.

Prerequisites​

  • Docker Desktop or compatible engine running locally.
  • Python 3.12 and make on your PATH.
  • The alphaswarm runtime repo cloned next to its siblings (alphaswarm_platform, alphaswarm_client, alphaswarm_core, alphaswarm_agents, …) under one workspace root. A lone monolith checkout is not enough for frontend or extracted-package work. See Repository orientation.

One-paste quickstart​

# 1. Pull the canonical compose stack.
make dev

# 2. Wait for the gateway's /readyz to return 200.
curl http://localhost:3000/readyz

# 3. Run the bundled example backtest.
docker compose exec alphaswarm-core alphaswarm-backtest \
    --config configs/strategies/momentum.yaml \
    --start 2024-01-01 --end 2024-06-30

If the third command returns a JSON summary with non-zero sharpe and total_return, your dev stack is healthy.

What just happened​

  • make dev boots the canonical compose stack defined by alphaswarm_platform/deployments/compose/docker-compose.base.yml plus docker-compose.local.yml + docker-compose.override.yml. 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, published on host port 3000). The Iceberg catalog is an embedded PyIceberg SQL catalog, not a separate REST service, in this default topology.
  • alphaswarm-core itself only listens on port 8000 inside the compose network (no host port is published for it by default), so curl http://localhost:3000/readyz — the alphaswarm-client gateway's own probe — is the host-reachable check. To hit alphaswarm-core's own stricter /readyz (which validates the migrated Postgres schema), run it from inside the network, e.g. docker compose exec alphaswarm-core curl -fsS http://localhost:8000/readyz. Migrations run automatically on first boot via the alphaswarm-core container's entrypoint.
  • The backtest command dispatches a Celery task that pulls the example momentum strategy, runs it against the seeded data, and writes a backtest_runs ledger row.

Next steps​

  1. Want to see the run in the UI? Open http://localhost:3000 — that is the unified operator UI (alphaswarm_client).

  2. Frontend Development? If you want to run the operator UI (alphaswarm_client) in development mode:

    cd ../alphaswarm_client
    pnpm install
    pnpm dev

    See Frontend Guidance for more details.

  3. Want to add your own strategy? Read Recipe: Add a strategy.

  4. Want to set up paper trading? Read Concept: paper trading followed by Tutorial: first paper trading session.

  5. Want to deploy this to Kubernetes? Read How-to: Kubernetes deploy or the Cluster Deployment Runbook.

If it does not work​

The /readyz probe is the single canonical health check. If it returns non-200 within 60 seconds:

  • Check docker compose logs alphaswarm-core for migration errors.
  • Confirm Postgres is reachable: docker exec alphaswarm-postgres pg_isready.
  • Confirm Redis is reachable: docker exec redis-stack redis-cli ping.

If the backtest command itself errors out, the most common cause is a stale Iceberg manifest from a prior dev cycle. Tear down with make down && docker volume prune -f and re-run.

For deeper debugging, see How-to: incident response.