Operational Guide

This page gives an operator-oriented map for using, administering, deploying, and troubleshooting AlphaSwarm services.

Service usage entrypoints

User type	Entry point	Repositories	Notes
Public visitor	Marketing/docs/legal site	`alphaswarm_website`, `alphaswarm_docs`	Public site should not call privileged APIs.
Hosted customer/operator	Authenticated platform dashboard	`alphaswarm_ui`, `alphaswarm_auth`, `alphaswarm_controller`, `alphaswarm_api`	Entra-only login; BFF proxies authenticated requests.
AlphaSwarm staff	Staff admin	`alphaswarm_admin`, `alphaswarm_auth`	Tenant onboarding/admin workflows and internal management.
Local power user	Local client and CLI	`alphaswarm_client`, `alphaswarm_cli`, `alphaswarm_local`	Local/hybrid development and operator workflows.
Developer/agent builder	IDE, MCP, agent runtime	`alphaswarm_ide`, `alphaswarm_mcp`, `alphaswarm_agents`	Tool/MCP connectivity and agent spec/runtime work.
Worker operator	Worker CLI/process	`alphaswarm_worker`	OAuth device flow, registration, Celery and optional engine nodes.
Platform operator	Ops console	`alphaswarm_ops_console`, `alphaswarm_platform`, `alphaswarm_local`	Privileged fetch/deploy/action UI; keep confirm gates for production.

Use alphaswarm_admin for staff-mediated tenant-link and customer onboarding workflows.
Ensure alphaswarm_auth provider adapters, RBAC roles/scopes, and device/WebAuthn settings are configured for the target environment.
Verify hosted UI still uses Entra-only auth and that /signup compatibility flows redirect into the approved login path.
Validate tenant router OIDC issuer/audience/JWKS settings before exposing a cell.
Confirm tenant/workspace RLS migrations and default tenancy seed rows before enabling strict enforcement.

Install or deploy alphaswarm_worker.
Authenticate with OAuth device flow.
Register the device/worker with an operator-approved name.
Run Celery queues or optional engine nodes only after verifying role/scopes and queue assignment.
For production, require authentication/registration flags rather than permissive local defaults.

Author or update an AgentSpec in the runtime-owned repository or approved registry path.
Hash-lock and register the spec before execution.
Route workflows through controller/orchestration surfaces.
Emit AGENT/TOOL/RETRIEVAL/EVAL spans to alphaswarm_observe.
For model changes, require dataset/model/prompt cards, eval gates, and promotion records in alphaswarm_mlops.

Operation	Preferred authority	Guardrail
Hosted platform rollout	`alphaswarm_platform`	Use Helm/Terraform/CD runbooks; finish P0 go-live prerequisites first.
Local/hybrid stack	`alphaswarm_local`	Keep local Compose/Helm separate from hosted production.
Operator UI deploy action	`alphaswarm_ops_console`	Use predeclared actions, confirm-gated production, no ad-hoc shell commands.
Docs publication	`alphaswarm_docs`	Run docs CI/link checks before merging.
Service package release	Owning service repo	Update changelog/changeset and validate package-specific tests.

Symptom	First checks	Likely repos
User cannot log in	Entra tenant link, session/BFF route, auth service health, tenant router JWT validation.	`alphaswarm_ui`, `alphaswarm_auth`, `alphaswarm_platform`
Request routes to wrong cell	Tenant registry, pinned tenants, tier claim, rendezvous hash config, router readiness.	`alphaswarm_platform`
Tenant data missing or blocked	RLS context, workspace/tenant headers, migrations, default seed rows.	`alphaswarm`, `alphaswarm_auth`, `alphaswarm_platform`
Agent run fails	AgentSpec hash/registry, MCP availability, KB/data dependencies, LLM provider config, eval gate.	`alphaswarm_agents`, `alphaswarm_mcp`, `alphaswarm_kb`, `alphaswarm_mlops`
Worker does not drain queues	Device auth/registration, queue names, broker connectivity, optional engine dependencies.	`alphaswarm_worker`, `alphaswarm_controller`, `alphaswarm_orchestration`
Hosted UI shows mock/stale data	BFF route wiring, controller/API backing service, E2E coverage, environment variables.	`alphaswarm_ui`, `alphaswarm_controller`, `alphaswarm_api`
Telemetry gap	SDK integration, span taxonomy, exporter endpoint, privacy filters, ingestion service roadmap.	`alphaswarm_observe`, `alphaswarm_observe_js`, `alphaswarm_kb_federation`, `alphaswarm_research`

Default to read-only reconnaissance before any live operational change.
Do not run destructive Kubernetes, Helm, Terraform, Cloudflare, AWS, or database mutations without an explicit gate and runbook.
Do not touch live trading flows in the alphaswarm namespace without signed approval.
Never print tokens, kubeconfigs, private keys, cookies, raw secret payloads, or credential files in logs/docs/issues.
Prefer metadata-only diagnostics and redacted summaries.
Keep future mutating control behind controller /manage governance rather than direct ad-hoc cluster actions.