Personalization & Status

The home page (/) and sidebar adapt to your deployment via two layers: identity envs (cosmetic — name, logo, brand color, cloud flag) and the /status endpoint (live setup readiness + activity).

Identity envs

All identity envs are read on every /status request. Set them in your .env, Docker compose, or via swarm_config — global-scope writes auto-trigger a reload (debounced ~250ms) so the new value lands in process.env and integrations re-init without an explicit POST /api/config/reload. Unset envs fall back to neutral defaults.

Examples

# Custom-branded self-hosted swarm
SWARM_ORG_NAME="Acme Engineering"
SWARM_ORG_LOGO_URL="https://acme.example.com/logo.png"
SWARM_BRAND_COLOR="#ff5500"
SWARM_MARKETING_URL="https://swarm.acme.example.com"

# Cloud deployment
SWARM_CLOUD=true
SWARM_ORG_NAME="Acme on swarm.example.com"
SWARM_ORG_LOGO_URL="https://swarm.example.com/logo.png"

# Vanilla self-hosted, no marketing
# (all identity envs unset — defaults apply)

GET /status

The single source of truth the UI leans on for "what does this swarm look like, what's set up, what's missing." Cheap (env reads + one SQL aggregate), zero side effects, no upstream calls.

Response shape

{
  "identity": {
    "name": "Acme Engineering",
    "logo_url": "https://acme.example.com/logo.png",
    "brand_color": "#ff5500",
    "is_cloud": false,
    "marketing_url": "https://swarm.acme.example.com",
    "hide_cloud_promo": false,
    "org_id": "org_acme_123"
  },
  "setup": [
    {
      "id": "harness",
      "label": "Harness configured",
      "state": "verified",
      "hint": "Live test passed within the last hour.",
      "action_url": "/integrations",
      "provider": "claude"
    },
    // … 6 more milestones
  ],
  "activity": {
    "agents_online": 3,
    "leads_online": 1,
    "recent_tasks_count": 42
  },
  "agent_fs": {
    "configured": true,
    "base_url": "http://agent-fs:7777"
  }
}

The full schema (Zod-validated) is in src/http/status.ts. See the auto-generated API reference for the wire contract.

Setup milestones

Seven milestones in fixed order. Each carries a state: unverified (not even configured), configured (env present but never live-tested), or verified (live-tested OR DB-backed proof).

The harness milestone also carries a typed provider?: ProviderName field so the UI knows which provider name to send to /status/test-connection.

Test-connection

POST /status/test-connection issues a real upstream call for the configured provider. Credential acceptance mirrors what each adapter accepts at runtime — OAuth users (Claude Pro/Max via claude CLI login, Codex ChatGPT OAuth) work without any API-key envs set.

OAuth tokens get a presence check rather than a real upstream call. The OAuth-bearer-with-/v1/models contract isn't a stable public surface, and OAuth flows have their own refresh logic (handled at adapter boot, not here) — a "real" check that fails on a stale-but-refreshable token would be a worse UX than an optimistic presence check. The runtime adapter remains the source of truth for whether a token actually works.

5-second timeout via AbortController. Errors run through scrubSecrets before return. On success, the result is cached in-memory keyed by provider, and /status reports harness.state === "verified" until SWARM_VERIFY_TTL_MS elapses or the API restarts.

curl -s http://localhost:3013/status -H "Authorization: Bearer $API_KEY"

curl -s -X POST http://localhost:3013/status/test-connection \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider":"claude"}'

Per-agent harness_provider

Workers report their HARNESS_PROVIDER env on registration into the agents.harness_provider column (migration 054). Operators can re-assign without restarting via:

curl -X PATCH http://localhost:3013/api/agents/<agent-id>/harness-provider \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"harness_provider":"codex"}'

The current behavior is forecast-only — the worker keeps using its env-set provider until it restarts, at which point the env wins on re-register. Full dynamic harness switching (worker boots without HARNESS_PROVIDER, picks up provider + creds from the API on demand) is tracked in DES-359.

Home page

The home page (/) consumes /status and renders:

1. Activity — leads online, agents online, tasks in last 24h.
2. Setup checklist — harness, integrations group (Slack + GitHub with "All integrations →" and "Docs ↗" links), workers, first task.
3. First steps + Storage — Phase 3 fills "First steps" with a recommended starter template based on detected integrations; Storage shows the agent-fs card.

If /status returns 404 (older API server), the home page redirects to /dashboard and the sidebar's "Home" item is hidden — older deployments degrade gracefully.

Related

• API reference: /status
• Harness configuration
• Harness providers
• Deployment