Skip to main content

Hybrid local backend

A self-hosted AlphaSwarm backend that runs outside the hosted cluster — on a developer laptop (Phase 1, linked testing) or on a B2B tenant's own infrastructure (Phase 2, self-hosting) — and is reached from the hosted platform over the existing device-paired reverse tunnel (hard rule 64). The local box dials OUT, so no inbound network exposure is required; the user's token rides through the tunnel verbatim and the local backend authorizes the human against the same hosted alphaswarm_auth.

This is distinct from the Local platform overlay, which is about running AlphaSwarm standalone for local development.

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

  • Local backend services run on the client machine.
  • Compose is the default local orchestration path.
  • The hosted connection uses the hosted-link/device tunnel flow.
  • alphaswarm-cli local dev ... is the recommended user/operator facade for plan, init, build, up, connect, status, logs, and down.
  • alphaswarm-local remains the lower-level package/service primitive that owns stateful local backend lifecycle details, including Compose/k3d orchestration, local state, doctor checks, license state, and tunnel daemon control.

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

Auth and tunnel boundary​

Azure CLI/Entra profile discovery can help find the tenant id for a hosted login, but it is only a convenience. AlphaSwarm platform auth still uses the AlphaSwarm CLI device login:

alphaswarm-cli auth login --device --entra-tenant <tenantId>

Do not treat Azure CLI tokens as the AlphaSwarm platform session. The hosted auth flow remains responsible for login, device pairing, device certificates, and license state. Cloudflare DNS is deferred and unsupported for the personal-hosted-link profile; use the hosted-link/device tunnel connection path instead.

The implementation lives in the alphaswarm_local sibling repo. Canonical documentation:

  • Design — ../../../../alphaswarm_local/docs/design.md
  • Enhancement plan — ../../../../alphaswarm_local/docs/enhancement-plan.md (as of this review, docs/enhancement-plan.md is referenced throughout alphaswarm_local's own AGENTS.md and docs/design.md but is not present in the repo checkout — verify it still exists before relying on it)
  • Implementation + migration guide — ../../../../alphaswarm_local/docs/implementation-migration-guide.md
  • Cursor implementation prompt — ../../../../alphaswarm_local/docs/cursor-implementation-prompt.md
  • Boundary contract — ../../../../alphaswarm_local/AGENTS.md

Related substrate: