How GlassHome Connects

Your dashboard looks like one thing, but under the hood there are three separate connections at work. Knowing what talks to what makes troubleshooting much faster: most problems come down to exactly one of these three links.

The short version

[Your device/browser]  <-------------->  [GlassHome server]  <-------------->  [Home Assistant]
     (phone, tablet,        every day: entity state,             your smart home
      laptop, kiosk)        commands, media, layouts              (lights, sensors,
                                                                    switches, etc.)

                       one-time hop, only while signing in:
[Your device/browser]  ----------------------------------------->  [Home Assistant]
                        (your browser is sent to HA's own
                         login page to approve the connection)

Two boxes do almost all the work: your device, and the GlassHome server (the one running on your Home Assistant box, your Docker host, or wherever you installed it). Home Assistant is the third box, and for day-to-day use, your device never talks to it directly.

Your browser talks to GlassHome, not to Home Assistant

When you open your dashboard, tap a light, or watch a camera feed, your device is talking to the GlassHome server. The GlassHome server is the one holding a connection to Home Assistant, and it relays what it needs to: it asks HA for the current state of your entities, and it sends your taps through to HA as commands.

Your device never opens its own connection to Home Assistant. This is true whether you’re on the same WiFi as your smart home or connecting from across town.

Why this matters when something goes wrong: if your dashboard loads but nothing updates, the problem is almost always between GlassHome and Home Assistant, not between your device and GlassHome. If the dashboard itself won’t load at all, the problem is between your device and the GlassHome server.

The one exception: signing in

There is exactly one moment where your device talks to Home Assistant directly: the first time you connect (or reconnect) an account. GlassHome sends your browser to Home Assistant’s own login page, you approve the connection there, and Home Assistant sends you back to GlassHome. This is the same pattern used by “Sign in with Google” or “Sign in with Apple,” just with your own Home Assistant instance playing that role.

Once that one-time approval is done, your device goes back to only talking to the GlassHome server. Home Assistant hands GlassHome a token (a long-lived permission slip) so it doesn’t need to ask you to log in again.

What runs through the GlassHome server

Everything that keeps your dashboard live goes through the GlassHome server, not around it:

• Live updates: GlassHome keeps one open connection (a WebSocket) to Home Assistant and pushes state changes out to every device viewing a dashboard, so a light turning on shows up everywhere within a second or so.
• Your Home Assistant token: stored on the GlassHome server, never sent to your phone or browser. Your device only ever holds a GlassHome session, not your HA credentials.
• Media: camera snapshots, media player art, and similar content are fetched by the GlassHome server and passed through to your device, rather than your device fetching them from Home Assistant on its own.

Why “.local” names fail on some devices, use the IP instead

Addresses like homeassistant.local rely on a discovery feature (mDNS) that not every device or network supports equally well. It often works fine on a phone at home, and then silently fails on a different device, a guest network, or after a router reboot.

If a .local address stops resolving, switching to the plain IP address of the device (for example 192.168.1.50 instead of homeassistant.local) sidesteps the discovery step entirely, since an IP address always works the same way regardless of what the network supports. The tradeoff is that an IP address can change if your router reassigns it, so a .local name is more convenient when it works, and an IP address is more reliable when it doesn’t.

Use the local address, not your remote URL

If you already reach Home Assistant from outside your home (DuckDNS, Nabu Casa, Cloudflare, your own domain), it is tempting to type that remote address into GlassHome’s Home Assistant field. It will often pass the check and even work, but it is the wrong address for this field.

GlassHome runs on your home network, right next to Home Assistant. If you give it your remote address, every tap and every update leaves your house, travels across the internet, and comes back in. Everything gets slower, and if your internet connection goes down, your dashboard stops working even though you are standing in the same room as both devices. With the local address (usually http://192.168.x.x:8123), your dashboard keeps working with or without internet.

One confusing case to know about: some routers cannot “loop back” to your own remote address from inside the house. Your phone may open the remote URL just fine while GlassHome reports it cannot reach it. Both are telling the truth; they sit in different places on the network. The fix is the same: give GlassHome the local address.

Your remote address still has a job, just not this one. To use your dashboard from outside your home, see Remote Access.

Signing in when this device can’t reach Home Assistant

The sign-in step is the one moment your device must reach Home Assistant itself. If it can’t, here is the decision tree:

1. You’re at home: use the Home Assistant sign-in. If the check is green, it will work.
2. You’re away, or on a device that can’t reach Home Assistant (like a kiosk tablet), and another device in your home is already signed in: use Quick Connect. The new device shows a short code, and you approve it from any signed-in device. No connection to Home Assistant is needed on the new device at all.
3. You’re away and nothing is signed in yet: the very first setup has to happen at home. That is a Home Assistant requirement, not a GlassHome one: its login page must load on the device doing the first sign-in.

Troubleshooting: which connection is failing

Related docs

• Connecting to Home Assistant: the sign-in step itself, URL formats, and reconnecting
• Remote Access: reaching GlassHome from outside your home network
• Concepts: how GlassHome, Home Assistant, and Hub relate