Relay Offline

The relay is the Mac app that bridges your local HomeKit devices to the Homecast cloud. When the relay is offline, remote access stops working.

Symptoms

What you see	Likely cause
"Relay unavailable" error in browser	Relay app not running or not connected
Devices don't load on homecast.cloud	Relay WebSocket disconnected
API returns timeout errors	Relay is unreachable
State updates stop in real-time	Relay lost connection mid-session
Dashboard shows homes but no accessories	Relay connected but HomeKit permission revoked

Menu bar indicator

The Homecast menu bar icon shows the relay's connection state:

Indicator	Meaning
Green	Connected and working
Yellow	Connecting or reconnecting
Red / Gray	Disconnected

If you don't see the Homecast icon in your menu bar, the app isn't running.

Diagnostic steps

1. Is the Mac app running?

   • Check the menu bar for the Homecast icon
   • If not running, open Homecast from Applications
   • Enable "Launch at Login" in the app's preferences to prevent this

2. Is the Mac awake and online?

   • macOS sleep disconnects the relay. Check System Settings → Energy and disable sleep, or use a Mac that stays on (Mac mini, Mac Studio).
   • Verify internet: try opening a website on the Mac

3. Is HomeKit permission granted?

   • System Settings → Privacy & Security → HomeKit → Homecast must be enabled
   • If it was recently revoked, re-enable it and restart the app

4. Can the relay reach the server?

   • Firewalls or network restrictions may block WebSocket connections to wss://api.homecast.cloud/ws
   • Corporate networks and some routers block long-lived WebSocket connections
   • Try connecting the Mac to a different network to isolate the issue

5. Is the server healthy?

   • Check https://api.homecast.cloud/health — should return 200 OK

Recovery

Action	When to use
Restart the Mac app	First thing to try. Quit and reopen from Applications.
Sign out and back in	If the app is running but shows disconnected. Refreshes your JWT session.
Recheck HomeKit permissions	If homes load but no accessories appear.
Reboot the Mac	If the WebSocket can't reconnect after multiple app restarts.
Check network	If nothing else works. Try a different network or disable VPN/firewall.

Connection lifecycle

The relay automatically:

• Reconnects if the WebSocket drops (with exponential backoff)
• Refreshes the connection every ~48 minutes to maintain connection stability
• Re-registers homes with the server on each new connection

If the relay has been offline for a long time, it will re-sync all home and accessory data when it reconnects. This may take a few seconds for large homes.