Skip to main content

Local Relay

Local Relay is an on-premises component for sites that need license enforcement with constrained cloud connectivity. The Host syncs outbound to the cloud, keeps a local store, and can serve LAN validation (and optional floating actions) without putting the full Management plane on-site.

Relay engine internals stay proprietary to the platform. Public docs describe the role and boundaries — not Host source layout or private messaging.

What Relay is for​

NeedRelay role
Intermittent / limited WANOutbound sync + local leases so the site keeps working between syncs
LAN productsLocal validation path for devices on the site network
No continuous HTTPSPair with air-gapped operator packages instead of (or between) sync windows

Relay does not open cloud message brokers from the Host. Continuous sync and air-gap handoff are separate transports with the same fail-closed crypto posture.

LAN activation, validation, and refresh require an active verified V2 License snapshot. A legacy entitlement-only store, offline grace, or a historical lease whose ProductId came from entitlement.Code cannot authorize a decision; validate/refresh report relay.host.no_snapshot until V2 state is delivered. See the Wave 74.15 cutover guide.

Safe LAN retries​

LAN activation, lease refresh, and device registration use a stable Idempotency-Key per logical attempt. Reusing the same key with the same request returns the original result even after a Host restart; changing the request under a live key returns 409 relay.host.idempotency_conflict. If the Host cannot recover its protected original result, it returns 503 relay.host.idempotency_unavailable and does not repeat the mutation. Keys must contain 1–128 printable ASCII characters without spaces.

Local usage reporting​

An authorized LAN client reports a usage fact with a signed edge-lan-v1 request to POST /api/edge/v1/usage/report using operation usage.report. The request supplies a UUIDv7 local event id, expected License and Product, normalized meter code, positive quantity and UTC occurrence time. Product in the request is not authority: Relay resolves Product, Tenant, Customer and the meter definition from the active Cloud-signed local generation and checks the client's Product scope.

Relay appends the fact to SQLite once. An exact local-event retry returns the same receipt; changed reuse returns 409. The Host freezes pending facts into immutable batches of at most 500 events and uploads the exact stored bytes with Gateway ES256 proof and a batch-derived idempotency key. A network failure or Host restart retries the same bytes. Local evidence is acknowledged only after Cloud returns the exact durable batch receipt. Usage facts do not grant or extend license rights.

Health and local diagnostics​

Anonymous GET /health and GET /ready responses contain only status, service, and version. They do not disclose tenant, customer, site, license counts, synchronization state, provider information, key ids, paths, or error details.

Detailed diagnostics use GET /api/edge/admin/v1/diagnostics. Access requires both a loopback caller and a separate RelayAdmin credential; LAN client and gateway credentials are not accepted. Host configuration stores only the credential's SHA-256 digest in RelayHostAdmin:CredentialSha256. The former anonymous GET /diagnostics path is removed. Security diagnostics expose only provider type names and the active signing key id, never credentials, key material, key coordinates, protected references, or configuration paths.

Vendor Console (operator)​

In Vendor Console, Offline / Floating / Relays list pages accept optional product context (productCode / productId query) and Operations nav exposes Offline + Floating alongside Relays. Local Relay enrollment uses a multi-step setup wizard (optional license bind → one-time token checklist → Offline air-gap export deep-link). Product filter query params are Console-side only in this release — Management list APIs remain tenant-wide.

Not the same as webhooks​

Customer webhooks are platform → your HTTPS URL event pushes for integrators. Relay sync is Host → cloud reconciliation plus local LAN validation. Do not configure a webhook URL expecting it to feed a Relay Host, and do not treat webhook delivery as proof of a signed lease.

When to use​

  1. Hospitality / branch sites with flaky WAN but many local clients.
  2. You want local enforcement plus periodic cloud reconciliation.
  3. Pure online Runtime-only products with stable connectivity → you may not need Relay.

Related​

Next steps​

  • Getting Started
  • Operations topics (deployment / troubleshooting) land in later public docs waves