Connecting to Home Assistant
After installing, 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
- Verifies the URL responds.
- Redirects to HA for OAuth consent.
- HA returns a refresh token to Dash.
- 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 or post in Discord and I’ll take a look.
Related docs
- Home Assistant Addon or Docker: install Dash first
- Quickstart: what to do once connected
- Remote Access: reach your dashboards from outside your network