---
title: "Connecting to Home Assistant"
description: "Pair GlassHome with your Home Assistant instance via OAuth. Setup wizard, demo mode, URL format pitfalls, and reconnection."
canonical: https://glasshome.app/docs/connecting
section: "Getting started"
updated: 2026-06-09
---
# Connecting to Home Assistant

After [installing](/docs/installation), open `http://<host>:3123`. The setup wizard runs on first launch.

## Connection methods

  ### OAuth (recommended)

Paste your HA URL. Authorize in the HA popup. The wizard returns automatically. No tokens to copy or rotate.
  ### Demo Mode

Explore with simulated entities, no HA needed. Pick it from the welcome screen. Ready for the real thing? Choose Exit demo in Settings, then connect your HA from the welcome screen.

## Entering the URL

The URL must include the protocol and the port HA is actually listening on.

| Setup                                    | URL example                                  |
|------------------------------------------|----------------------------------------------|
| HA on the same LAN, plain HTTP           | `http://homeassistant.local:8123`            |
| HA on a fixed IP                         | `http://192.168.1.100:8123`                  |
| HA behind HTTPS (reverse proxy / Nabu)   | `https://ha.example.com`                     |

> **The URL must match what HA serves:** If HA is behind HTTPS, use `https://`. If HA is plain HTTP, use `http://`. A mismatch fails silently or returns a confusing CORS error.

## What the wizard does

1. Verifies the URL responds.
2. Redirects to HA for OAuth consent.
3. HA returns a refresh token to Dash.
4. Token is stored in Dash's local SQLite (never sent to Hub).

## Reconnecting

To swap to a different HA instance, or repair a broken connection: **Settings > Connections > Reconnect**. Your dashboards and layouts are stored locally and remain after reconnecting; only the HA auth token is replaced.

## Privacy

Dash talks to HA directly over WebSocket. Entity state, your HA URL, and the auth token never leave your network. Hub is not in this path.

## Troubleshooting

| Symptom | Likely cause | Fix |
|---------|-------------|-----|
| Wizard rejects the URL | Missing protocol or wrong port. | Try the URL in a browser tab first. Add `http://` or `https://` and confirm the port. |
| Stuck on "Authorizing..." | Popup blocked, or HA is unreachable from your browser (not just from the Dash host). | Allow popups for the Dash URL, then confirm your browser can reach HA directly. |
| Mixed-content / CORS error in console | HTTPS Dash URL + plain HTTP HA URL (or vice versa). | Options: serve HA over HTTPS (Nabu Casa or a reverse proxy), access Dash over plain HTTP on your local network, or use a VPN so both are on the same network. |
| Connection drops after restart | HA was rebooted while the WebSocket was open. | Refresh the page. Dash reconnects automatically. |
| Connected but entities not loading | Token user has no entity permissions in HA. | Re-authorize with a fully-permitted HA user. |

Still stuck? See [Troubleshooting](/docs/troubleshooting) or post in [Discord](https://discord.gg/FJYdeDmrzv) and I'll take a look.

## Related docs

- [Home Assistant Addon](/docs/addon) or [Docker](/docs/docker): install Dash first
- [Quickstart](/docs/quickstart): what to do once connected
- [Remote Access](/docs/remote-access): reach your dashboards from outside your network