Operations runbook - Local environment lifecycle

Use this runbook for a personal or limited-scope development environment that runs AlphaSwarm backend services on a developer workstation and connects them to the hosted platform through the hosted-link device tunnel.

The recommended operator surface is:

alphaswarm-cli local dev

That command group is a facade for the lifecycle. It keeps the operator flow in one place while leaving stateful local orchestration with the lower-level alphaswarm-local package.

Profile boundaries

The first supported profile is personal-hosted-link.

Boundary	First profile behavior
Profile	personal-hosted-link is the default.
Local orchestration	Compose is the default orchestration path.
Hosted connection	The local backend connects through hosted-link/device tunnel.
Identity authority	Hosted AlphaSwarm auth remains the authority for login, device pairing, device certificates, and license state.
Scope	Personal or limited-scope development. Do not use this profile for a shared production self-hosted cell.
Cloudflare DNS	Cloudflare DNS is deferred and unsupported for this first profile. Use the device tunnel connection path instead.

Adjacent local modes still exist. Standalone compose, Terraform/k3d local platform work, edge/tower deployments, minimum AWS, and future production self-hosted modes are separate paths with their own runbooks.

Authentication and tenant discovery

If your hosted login uses Microsoft Entra, Azure CLI can help discover the tenant attached to your active shell profile:

az account show --query tenantId -o tsv

This az account show tenant/profile is only a convenience for finding the tenant id. The AlphaSwarm platform login is still a separate device login:

TENANT_ID="$(az account show --query tenantId -o tsv)"
alphaswarm-cli auth login --device --entra-tenant "$TENANT_ID"

Do not treat the Azure CLI session as the AlphaSwarm session. The local dev workflow uses the AlphaSwarm CLI auth session created by alphaswarm-cli auth login --device --entra-tenant <tenantId>. The CLI may use the tenant id you provide, but it does not store or use Azure CLI access tokens directly for this platform login.

Lifecycle

Run the lifecycle from a checkout that has the AlphaSwarm CLI installed and can reach Docker/Compose.

1. Plan

alphaswarm-cli local dev plan --profile personal-hosted-link

Use plan first on a new machine or after toolchain changes. It should inspect local prerequisites such as Docker, Compose, optional k3d tools, keyring availability, hosted URL settings, existing local config, and command availability. It should report what each later step would delegate without changing local state.

2. Init

alphaswarm-cli local dev init --profile personal-hosted-link

init prepares the local configuration for the selected profile and delegates local backend initialization to the lower-level package primitive:

alphaswarm-local init

Keep user-edited local config intact unless the command explicitly asks before overwriting it.

3. Build

alphaswarm-cli local dev build --profile personal-hosted-link

build requests the images or artifacts needed by the local backend for this profile. It should use existing build surfaces rather than introducing a second build system in the operator facade.

4. Up

alphaswarm-cli local dev up --profile personal-hosted-link --orchestrator compose

up starts local services through Compose by default. Under the hood, this is the same ownership boundary as:

alphaswarm-local up

Keep service startup separate from hosted connection setup. After local services are healthy, run connect.

5. Connect

alphaswarm-cli local dev connect --code <pairing-code> --profile personal-hosted-link

--code (the hosted Connected Backend pairing code) is required — the command has no default and errors without it. connect verifies the hosted AlphaSwarm login, guides or verifies device pairing, verifies/provisions the device certificate through hosted auth, and starts or verifies the hosted-link/device tunnel. Cloudflare DNS is not a supported connection mode for this first profile.

If the CLI reports that login is missing or stale, run the device login again:

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

6. Status

alphaswarm-cli local dev status --profile personal-hosted-link

Status should combine local service state, doctor signal, device credential state, license lease state, tunnel state, and hosted control-plane reachability. Healthy output should make the connected surfaces obvious. For example, a human status view may include a Connected Backends section covering local compose services and the hosted-link/device tunnel.

local dev status does not currently accept a --json flag — only plan does, for previewing the lifecycle plan itself (local dev plan --json). The lower-level alphaswarm-local status doesn't expose one either; there is no machine-readable status output today.

7. Logs

alphaswarm-cli local dev logs --profile personal-hosted-link

Use logs to inspect local service or tunnel logs through the facade. If a focused selector is available in your CLI version, use it for a specific service or tunnel stream; otherwise fall back to the lower-level package logs for detailed debugging.

8. Down

alphaswarm-cli local dev down --profile personal-hosted-link

down stops local services through the same ownership boundary as:

alphaswarm-local down

Do not use lifecycle shutdown as a destructive reset. Data volume removal, credential deletion, and tunnel/device revocation should stay explicit and separate.

Lower-level package primitives

alphaswarm-cli local dev is the recommended operator facade for the personal hosted-link lifecycle. It is the path to use in runbooks, onboarding, and routine personal environment work.

alphaswarm-local init/up/link/status/doctor remains the lower-level package primitive for package maintainers, deep troubleshooting, and direct local backend development. Use those commands when you need to inspect or debug the local orchestration layer itself. Prefer returning to the facade once the underlying issue is understood.

Troubleshooting

Symptom	Fix
local dev plan reports no Docker or Compose support	Install Docker Desktop or a compatible Docker/Compose runtime, then rerun alphaswarm-cli local dev plan.
local dev connect reports missing hosted login	Run alphaswarm-cli auth login --device --entra-tenant <tenantId> and retry alphaswarm-cli local dev connect.
The Azure tenant is unclear	Use az account show --query tenantId -o tsv to discover the active Azure CLI tenant id, then pass that id to the AlphaSwarm device login.
local dev status shows disconnected tunnel state	Retry alphaswarm-cli local dev connect, then inspect alphaswarm-cli local dev logs for tunnel details.
A runbook mentions Cloudflare DNS for local hosted link	Treat it as out of scope for personal-hosted-link; use hosted-link/device tunnel for this profile.