Skip to main content

alphaswarm-client

Catalog date: 2026-08-07.

The frontend for local power users — operators running AlphaSwarm on a laptop, in a tower cluster, or inside a self-hosted cell. It bundles a React 19 + Vite SPA, the legacy Solara research UI, and a thin FastAPI gateway that proxies to alphaswarm-core and alphaswarm-cp.

This is not the cloud customer dashboard — that is alphaswarm-ui, which targets app.alpha-swarm.ai.

Identity​

FieldValue
Service idalphaswarm-client
Rolefrontend
Packagealphaswarm_client/
Image (key)frontend
Built fromalphaswarm_client/Dockerfile (3-stage: ui-builder → solara-builder → production) and Dockerfile.tf (Terraform-built variant)

Wire​

FieldValue
ProtocolHTTP/1.1 + WebSocket
Port8080 (container, EXPOSE 8080 in the Dockerfile) → 80 (ClusterIP Service port, targetPort back to the container's 8080) → 3000 (host, local dev)
HealthGET /health (Docker HEALTHCHECK + k8s liveness/readiness probes)
Public URLper-cell ingress (e.g. https://alphaswarm.<cell>.alpha-swarm.ai); local dev http://localhost:3000

Deployment surfaces​

SurfaceWhere
Composeservice client in alphaswarm_platform/compose/docker-compose.yml; alphaswarm-client in deployments/compose/docker-compose.local.yml
Kustomizedeployments/kubernetes/base/alphaswarm-client/ — Deployment + Service + HPA + PDB
AlphaSwarm CRAlphaSwarmClient

Dependencies​

Upstream (HTTP):

  • alphaswarm-core (/api/*, /ws/*) — every business call.
  • alphaswarm-cp (/manage/*, /auth/*) — workload lifecycle and identity.

Downstream:

  • Browser tabs on operator workstations.

Frontend conventions​

  • Vite + React 19 + TanStack Query + zustand for state.
  • Backend targets are build-time variables: VITE_API_URL, VITE_WS_URL, VITE_OBSERVE_URL, VITE_OTEL_URL, and VITE_JAEGER_URL. Local development proxies /alphaswarm-api, /alphaswarm-ws, /alphaswarm-observe, and /alphaswarm-otel to those targets.
  • WebSocket pipeline is throttled (50ms coalescing) per the frontend rule in the private alphaswarm_internal repo. (As of 2026-07-19, alphaswarm/.cursor/rules/ only carries a pointer to this SSoT repo.)
  • Solara legacy routes mounted at /legacy/*; sunset window per alphaswarm-client/AGENTS.md.

Operations​

  • Scaling: base HPA (deployments/kubernetes/base/alphaswarm-client/hpa.yaml) targets cpu=60% / memory=70%, min=1 / max=10; the prod overlay patches this to min=3 / max=20.
  • Bundle size budget: could not verify — alphaswarm_client/.github/workflows/ci.yml runs typecheck / lint / Vitest coverage / Playwright E2E, but does not run pnpm build or any bundle-size check at all today. No size-limit/bundlesize tooling or budget was found in package.json or vite.config.ts either.
  • CSP: could not verify — no Content-Security-Policy configuration was found in alphaswarm_client (Dockerfile, source) or in its deployments/kubernetes/base/alphaswarm-client/ kustomize base.

See also​