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.

Need to control something right now?

If you have Homecast on an iPhone or iPad that's been invited to the home in Apple Home, it keeps working on its own — Local Mode takes over automatically when the relay can't be reached, and a Local Mode badge appears next to the search icon. It covers accessories, scenes and groups; automations and notifications still need the relay, so work through the steps below as well.

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

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.

While you work through those, Local Mode keeps an iPhone, iPad or second Mac usable. It serves only the device it's running on, though — everyone else in the household is still waiting on the relay.

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.

Cloud Managed Relay

If you're using Cloud Managed (no self-hosted relay), the relay is operated by Homecast:

• Cloud relays are monitored — we detect and resolve outages automatically
• No action needed on your end — you don't need to restart anything
• Contact support if your cloud relay shows as offline for an extended period
• Your devices remain controllable via the Apple Home app during any downtime