Local platform overlay

AlphaSwarm uses "local" for two adjacent but different operating modes:

1. Personal hosted-link local backend: backend services run on a developer workstation and connect to the hosted platform through the hosted-link/device tunnel. For this limited-scope workflow, use alphaswarm-cli local dev ... as the recommended user/operator facade.
2. Local platform overlay / standalone single-machine deployment: a Compose-based local stack that runs without linking to the hosted platform. This page documents that standalone overlay.

Personal hosted-link local backend

The alphaswarm-local package enables a "Bring Your Own Backend" (BYOB) model. You run the backend locally, and it dials out to the hosted AlphaSwarm platform, allowing you to use the hosted UI with your local data and compute.

For personal or limited-scope hosted-link development, the first supported profile is personal-hosted-link:

• Compose is the default local orchestration path.
• The hosted connection uses the hosted-link/device tunnel flow.
• alphaswarm-cli local dev ... is the recommended lifecycle facade for planning, initialization, service startup, connection, status, logs, and shutdown.
• alphaswarm-local remains the lower-level package/service primitive that owns stateful local backend lifecycle details such as Compose/k3d orchestration, local status, doctor checks, license state, and tunnel daemon control.
• Azure CLI/Entra profile discovery is only a convenience for finding a tenant id. Platform auth still uses alphaswarm-cli auth login --device --entra-tenant <tenantId>.
• Cloudflare DNS is deferred and unsupported for this first profile; use the hosted-link/device tunnel connection path instead.

Use the local environment lifecycle runbook for the current operator flow.

See the alphaswarm_local README for lower-level package details.

Platform overlay (Standalone)

Audience: a developer who wants to run AlphaSwarm standalone, without attaching to the rpi_kubernetes cluster or the hosted platform. The platform overlay (alphaswarm_platform/compose/docker-compose.platform.yml) brings the data + observability services AlphaSwarm code expects into the local compose stack.

This standalone local platform overlay is not the same workflow as personal-hosted-link: it does not assume hosted platform auth, a device tunnel, or hosted-link lifecycle commands.

The rpi kubernetes/ tree stays untouched — these are copies, not relocations. AlphaSwarm attaches to either the local services or the cluster through the KubernetesAdapter abstraction.

Compose-up matrix

Goal	Command
Just the AlphaSwarm API + workers	docker compose up -d
AlphaSwarm + visualization stack (Trino, Polaris, Superset, Dagster, Dask, Ray)	docker compose -f alphaswarm_platform/compose/docker-compose.yml -f alphaswarm_platform/compose/docker-compose.viz.yml --profile visualization up -d
Full local platform parity (adds Apicurio + real Airbyte + DataHub + Loki + Vector + VictoriaMetrics)	docker compose -f alphaswarm_platform/compose/docker-compose.yml -f alphaswarm_platform/compose/docker-compose.viz.yml -f alphaswarm_platform/compose/docker-compose.platform.yml --profile visualization --profile platform up -d

The platform overlay also activates the visualization profile's services it depends on (Polaris, Trino, Dagster). Don't pass --profile platform alone — the AlphaSwarm webui still depends on Superset from the viz overlay.

Services added by the platform overlay

Service	Container	Default host port	Wires into
apicurio (Schema Registry)	alphaswarm-apicurio	8090 -> 8080	ALPHASWARM_SCHEMA_REGISTRY_URL already supports the URL knob
airbyte-db	alphaswarm-airbyte-db	(internal)	Postgres backing for real Airbyte
airbyte-server-real	alphaswarm-airbyte-server-real	8005 -> 8001	Real Airbyte API (the dev stub at airbyte-server keeps running on :8002)
airbyte-webapp	alphaswarm-airbyte-webapp	8001 -> 80	UI for real Airbyte
datahub-gms	alphaswarm-datahub-gms	8081 -> 8080	ALPHASWARM_DATAHUB_GMS_URL=http://datahub-gms:8080
datahub-frontend	alphaswarm-datahub-frontend	9002 -> 9002	DataHub UI
loki	alphaswarm-loki	3100 -> 3100	Log aggregation; OTel collector + agents push here
vector	alphaswarm-vector	(none)	Tails Docker container logs and ships to Loki
victoriametrics	alphaswarm-victoriametrics	8428 -> 8428	Long-term metrics; scrapes the existing OTel collector + AlphaSwarm API

Sub-profiles (documented but not enabled by default)

The plan keeps these out of the default platform set because the user opted out of "full parity":

• platform-rag — RAGFlow + Milvus stack (heavy; pulls a vector DB).
• platform-jh — JupyterHub.

Add them yourself if needed by extending alphaswarm_platform/compose/docker-compose.platform.yml or shipping an alongside docker-compose.platform.<profile>.yml.

Smoke test sequence

1. docker compose -f alphaswarm_platform/compose/docker-compose.yml -f alphaswarm_platform/compose/docker-compose.viz.yml -f alphaswarm_platform/compose/docker-compose.platform.yml --profile visualization --profile platform up -d
2. curl http://localhost:8428/-/ready — VictoriaMetrics
3. curl http://localhost:3100/ready — Loki
4. curl http://localhost:8081/health — DataHub GMS
5. curl http://localhost:8090/apis — Apicurio
6. curl http://localhost:8005/api/v1/health — real Airbyte
7. docker compose ps — every service should be healthy or running

Where the rpi cluster fits in

When ALPHASWARM_CLUSTER_MGMT_URL is set, the RpiClusterAdapter auto-promotes and AlphaSwarm forwards Kafka admin + Flink session-job + alphavantage stream operations to the homelab management API. Setting both attach paths side-by-side is fine — AlphaSwarm routes the call wherever the active adapter says.

Cleanup

docker compose -f alphaswarm_platform/compose/docker-compose.yml -f alphaswarm_platform/compose/docker-compose.viz.yml -f alphaswarm_platform/compose/docker-compose.platform.yml --profile visualization --profile platform down

Volumes are preserved; pass -v to wipe them.