> ## Documentation Index
> Fetch the complete documentation index at: https://devlookout.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup session protocol

> Follow the account-bound onboarding, deployment identity, and recovery protocol.

> For the complete documentation index, see [llms.txt](https://devlookout.com/llms.txt). Markdown versions are available by appending `.md` to page URLs.

Lookout uses an authenticated-browser-created, account-bound setup session. The browser receives a high-entropy `setup_token` and embeds it in the coding-agent prompt. The token expires quickly, is stored only as a hash by the authority, and is consumed atomically by the first valid claim. Tenant and user identifiers always come from the authenticated browser context.

The installer performs bounded authoritative read-only VM discovery from provider APIs available to the current agent terminal before claiming the token. It selects a central Linux VM deterministically and submits `deployment_identity.public_key_spki_pem` and the exact discovered `installation_scope`. The agent terminal is an orchestration host, not an implicit target. The scope contains `central_vm_id` plus a bounded unique `vms` list. The service validates and stores it, returns the exact normalized scope to the installer, and the fleet installer refuses to probe or modify anything outside that list.

The protocol is:

1. `POST /v1/setup-sessions` requires an authenticated browser and an empty JSON object. It returns `session_id`, `setup_token`, and `expires_at`.
2. The small bootstrap sends the token through the request body to `POST /v1/setup-sessions/connect` before downloading the release. This records `connected` without consuming the token, reflecting it, or releasing provisioning.
3. Provider discovery runs in parallel while the browser continues polling. `POST /v1/setup-sessions/claim` then consumes `setup_token`, binds a canonical Ed25519 deployment identity and discovered scope, and returns `session_token`, `challenge`, `deployment_id`, and the normalized `installation_scope`.
4. `POST /v1/setup-sessions/{session_id}/prove` verifies the Ed25519 possession proof before releasing deployment-scoped provisioning.
5. `POST /v1/setup-sessions/{session_id}/bootstrap-key` publishes only the temporary restricted fleet public key for browser visibility and audit.
6. `POST /v1/setup-sessions/{session_id}/phases` accepts monotonic progress. Completion is rejected until the SaaS has received the first deployment snapshot.
7. An authenticated browser polls `GET /v1/setup-sessions/{session_id}`. After claim it also checks the deployment snapshot and displays the number of systems reporting live data while installation continues. It receives the dashboard URL after completion, preserving automatic redirect.

The old installer-created pairing, readable phrase, browser approval, and bootstrap confirmation routes do not exist. The installer cannot submit tenant or user identity. One active non-recovery deployment is allowed per account.

## Central recovery

Each accepted console snapshot is a central heartbeat. When `updated_at` exceeds the configured heartbeat timeout, the recovery monitor marks the deployment `central_missing`, creates one encrypted-at-rest single-use `lrc_` recovery token, exposes a recovery action in the authenticated dashboard, and sends email when Resend configuration is present. Claiming a recovery token retains the deployment ID but rotates its console credential. The same approved-scope contract applies, and recovery mode forces every remote collector to replace enrollment against the reinstalled central VM.