KKairoDockby beingkairo
Discord
Guide

Overlays and docks

KairoDock keeps local desktop routes separate from hosted OBS overlay URLs.

What to add to OBS

  • Chat dock for reading the unified feed in OBS.
  • Notifications dock for stream events and alerts.
  • Local overlay routes for sources that should stay on the streaming PC.
  • Hosted overlay URLs when KairoDock provides a local overlay token.
  • Preview mode before committing visual changes to a live scene.

Hosted overlay URLs

  • Chat overlay: /overlay/YOUR_TOKEN.
  • Alerts overlay: /overlay/YOUR_TOKEN/alerts.
  • Mixed debug overlay: /overlay/YOUR_TOKEN/events.
  • Use only the overlay URL generated by KairoDock. Do not place platform OAuth tokens, service keys, or publish secrets in OBS browser-source URLs.

Hosted overlay API

  • Desktop event pushes use POST /api/overlay/YOUR_TOKEN/events.
  • Runtime styling pushes can use POST /api/overlay/YOUR_TOKEN/settings.
  • The desktop app owns the local token and can reset or regenerate it; old OBS URLs stop receiving events once the app publishes to the new token.
  • The API broadcasts to the hosted overlay channel and does not create website users, sessions, dashboards, or database rows.

Recommended flow

  • Start KairoDock before opening OBS scenes that depend on local routes.
  • Use the local route or hosted overlay URL shown in the app for the source you want.
  • Add the route as an OBS dock or browser source depending on the use case.
  • Preview and adjust styling before using the source live.
  • Keep local routes and hosted overlay URLs separate so scenes do not depend on the wrong source.

Customization behavior

  • Hosted overlays follow the same customization concepts as localhost overlays: compact mode, font scale, alignment, timestamps, avatars, radius, shadows, spacing, and platform colors.
  • The desktop app should remain the source of truth for overlay settings. Hosted URLs can carry safe viewer-side options without exposing platform credentials.
  • Use the mixed events overlay with debug=1 when checking hosted Realtime status, derived channel, and received diagnostic events.

When a source is blank

  • Confirm KairoDock is running and the local route is available.
  • For hosted overlays, confirm the tokenized URL came from KairoDock.
  • Refresh the OBS dock or browser source.
  • Check diagnostics for recent route, Realtime, or connection errors.
  • Avoid rebuilding the source until the app status confirms the route is healthy.

Token safety

  • Hosted overlay URLs are public but unlisted; treat them like resettable scene links.
  • Reset or regenerate the overlay URL in KairoDock if a token is shared in the wrong place.
  • Overlay channels are derived from the token and never from platform OAuth material.