Configuration

Configuration

First-time setup (connect to Home Assistant)

The dashboard talks to HA directly over WebSocket from the browser, and the add-on does not store your token. On first open:

1. Click the gear / Settings icon in the dashboard.
2. Under Home Assistant, enter your Server URL and a Long-Lived Access Token.
   • Use your HA's IP address, e.g. http://192.168.1.10:8123 — many devices (tablets, Fire tablets, Fully Kiosk) can't resolve homeassistant.local, so the IP form is the reliable choice. (Port is 8123, HA's normal port.)
   • Create a token in HA → your Profile → Long-Lived Access Tokens.
3. Click Test connection, then Save & reload.

The token is kept in that browser's localStorage only — never written to disk or baked into the image.

Make sure the Server URL is reachable from the device viewing the dashboard. On tablets/kiosks, prefer the IP form (http://<HA-IP>:8123) — homeassistant.local often doesn't resolve there.

Remember connection on this server (opt-in)

By default the token lives only in the browser you typed it into, so each new device (tablet, kiosk) has to enter it again. Turn on Remember connection on this server under Settings → Home Assistant and save to store the URL + token server-side (/data/connection.json on the add-on). Any device that opens the dashboard without a local token then adopts the saved connection automatically and loads live data on first open.

• Off by default — the secure per-device behavior is preserved unless you opt in.
• Turning it back off clears the stored connection from the server.
• Anyone who can reach the dashboard can use the saved connection, so only enable it on a trusted local network. Since this is all local, you can change the token in HA at any time to revoke access.

Connection resolution order (local dev)

Values resolve: Settings (localStorage) → Vite env → default.

Source	Key
Settings modal	HA URL + long-lived token
.env	VITE_HA_URL, VITE_HA_TOKEN
Hard default	http://homeassistant.local:8123

---

Appearance

• Themes — Midnight, Slate, OLED Black, Light.
• Accent color — 8 swatches + a custom color picker. The accent recolors the whole UI (driven by an --accent-rgb triplet).
• Ambient effects — toggle the weather-reactive backdrop (rain/snow particles, lightning in thunderstorms) and time-of-day tint.

All animations respect prefers-reduced-motion: reduce.

---

Settings persistence

• App settings (HA URL, token, theme, accent) → localStorage (per browser/device).
• Shared connection (opt-in) → if Remember connection on this server is enabled, the URL + token are also stored server-side in connection.json (/data/connection.json on the add-on) so other devices auto-connect.
• Dashboard layout → server-side layouts.json via the Vite middleware (shared across devices on the same host); on the add-on it persists to /data/layouts.json and survives restarts/updates.

---

Dev preview overrides

AmbientBackdrop reads URL query params to preview ambient effects regardless of real conditions:

Param	Values	Effect
?precip=	rain snow none	Force the precipitation layer
?tod=	dawn day dusk night	Force the time-of-day tint

Example: http://localhost:3000/?precip=snow&tod=dusk. No params = real weather/clock.