Skip to content

Host Agent enrollment

Onboard Host Agents to a site (with or without Edge) using silent-install-friendly secrets and admin approval in Cloud UI. Implemented in Backend/internal/domain/hostagents (POST /v1/sites/:id/enrollment-secret, POST /v1/host-agents/enroll, POST /v1/host-agents/:id/approve).

Flow

Section titled “Flow”
sequenceDiagram
    participant Admin as Cloud admin
    participant Host as Host Agent
    participant Edge as Edge gateway
    participant Cloud as Cloud Backend
    participant UI as Cloud UI

    Admin->>Cloud: POST /v1/sites/:id/enrollment-secret
    Host->>Host: mDNS discover Edge (advertisement not yet implemented — always falls to Cloud today)
    alt Edge found
        Host->>Edge: POST /local/v1/enroll (secret)
        Edge->>Cloud: Proxy directly to POST /v1/host-agents/enroll
    else No Edge
        Host->>Cloud: POST /v1/host-agents/enroll (secret)
    end
    Cloud->>UI: Pending Host Agents (GET /v1/host-agents?status=pending)
    Admin->>UI: POST /v1/host-agents/:id/approve
    Note over Host,Cloud: host_token isn't pushed — the host polls by<br/>re-enrolling with the same secret+host_id.<br/>Once approved, that same call mints and<br/>returns a fresh host_token.
    Host->>Cloud: POST /v1/host-agents/enroll (poll, same secret+host_id)
    Cloud->>Host: {status: "approved", host_token, expires_in_seconds}

The Edge path is a pure proxy — Edge doesn’t track its own pending-host state; Cloud’s site_enrollment_secrets/host_agents tables are the sole source of truth.

Credentials

Section titled “Credentials”
CredentialUseLifetime
enrollment_secretBootstrap only; GPO/Intune ENROLLKEY= install param (no MSI in V1 — see Updates)Fixed 48h default (admin-configurable-per-generation is a tracked follow-up)
host_tokenRuntime auth: Ingestor POST /v1/ingest (Authorization: Bearer) for snapshots, Backend POST /v1/host-agents/token/refresh for rotation — minted/rotated only by Backend, validated by both services against the same host_agents tableTTL 30 days, refreshed by the agent ~24h before expiry (or by re-enroll polling, see above)

Known gap

Section titled “Known gap”

If an admin takes longer to approve a host than the enrollment_secret’s TTL, the still-pending host can no longer poll for its token (the enroll handler re-validates the secret on every call, including polls). Secret TTL (24–72h target) is meant to comfortably exceed approval SLA, but this is a real edge case if approval is slow. Tracked in root TODO.md.

Section titled “Related”