Skip to main content

Alpha Testing Deployment Runbook

This runbook covers the current AlphaSwarm alpha-testing topology. The legacy demo environment is not part of the active stack: do not start demo-mode UI components, seed demo data, or route operators through demo.alpha-swarm.ai.

Deployment Overview​

The current alpha setup is split across two machines:

  • MacBook: client-side apps, local dev servers, CLI tools, and browser sessions.
  • Local Ubuntu box: hosted platform services, Kubernetes workloads, and shared platform state.

Traffic from the MacBook should target the Ubuntu-hosted platform endpoints for alpha testing. Demo components should remain stopped.

Prerequisites​

  • Network reachability from the MacBook to the local Ubuntu box.
  • alphaswarm-cli configured for the alpha environment.
  • kubectl context, SSH access, or the approved management path for the Ubuntu-hosted platform.

Step-by-Step Deployment​

1. Verify the Ubuntu-hosted platform​

Confirm the platform workloads are up on the Ubuntu box and that no legacy demo workloads are running. alphaswarm-cli manage workloads status --env alpha is not a real command (manage has no workloads subgroup, and cp workloads only exposes halt-all/halt-status, not a general status --env query); the closest verified read-only equivalent is:

alphaswarm-cli status services

2. Start MacBook client-side apps​

Run the client apps and local servers on the MacBook, pointing their API and control-plane URLs at the Ubuntu-hosted platform:

pnpm --dir ../alphaswarm_client dev

3. Verify alpha connectivity​

Use the alpha endpoints or the MacBook dev server URLs. Do not verify against demo.alpha-swarm.ai:

curl -I https://alpha.alpha-swarm.ai

4. Confirm demo components are stopped​

Search workload names and environment flags before handing the environment to testers:

alphaswarm-cli status services | rg -i "demo|DEMO_MODE"

Alpha-Specific Configuration​

UI and API routing​

  • MacBook client apps should use the Ubuntu box for API/control-plane traffic.
  • alphaswarm_ui should run in normal alpha mode, not demo mode.
  • Any legacy *_DEMO_MODE flag should be unset or false for the active alpha stack.

Rate Limiting​

Alpha access is controlled by the current identity and access configuration for the alpha cohort. Do not rely on public demo rate-limit policy as an operator guardrail.

Troubleshooting Alpha Issues​

  • Client cannot reach API: Verify the MacBook points to the Ubuntu-hosted platform URL and the Ubuntu services are healthy.
  • Unexpected demo UI: Check for DEMO_MODE, sample-agent, or demo.alpha-swarm.ai settings in the running workload environment and stop the stale component.
  • Login issues: Verify the alpha identity provider and callback URLs, not the retired demo Auth0 tenant.

Further Documentation​

  • For UI integration details, see Frontend Guidance.
  • For general platform operations, see Operations Index.
  • For project-wide index, see the AlphaSwarm Index (alphaswarm_index repo).