Skip to content

Configuration

Jump to bottom
jv edited this page Jun 6, 2026 · 4 revisions

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.

Set up from scratch — no code required

Everything below is done in the running app; you never edit config.ts or layouts.json by hand:

  1. Connect. On first launch the guided onboarding asks for your HA URL and a long-lived token (create one in HA → Profile → Security), with a Test button to confirm before saving.
  2. Start blank. Open Settings → Dashboard data → Start blank to clear the sample layout and begin with an empty Home page plus a zero-config Media page. (Reset to default restores the bundled sample instead.)
  3. Add pages. Use PagesManager to create, rename, re-icon, reorder, and delete pages. Each page also has a board-type selector (Tiles, Sensor graphs, NOC servers, Cameras, Now Playing).
  4. Add tiles. In Edit mode, click + Add Tile and pick any entity from the searchable picker (lights, switches, covers, locks, climate, media, vacuum, sensors, scenes, scripts, buttons, and more). Drag to arrange; open per-tile settings for camera entity, links, quick actions, flyout options, slider direction, and size.
  5. Add scenes. Each page has a scene picker; scenes you add show with their HA friendly name and icon automatically.
  6. People appear automatically. Every person.* entity is discovered and shown in the header / People tracker — no configuration needed.
  7. Weather appears automatically. The header forecast + ambient backdrop pick up any weather.* entity; choose a specific one in Settings → Appearance if you have several.
  8. Theme it. Pick a theme + accent color in Settings.
  9. Monitor infrastructure (optional). Switch any page to the NOC (servers) board type in Manage Pages to build a monitoring dashboard for servers, UPSes, switches and Docker — see NOC / Servers Dashboard.

The bundled config.ts catalogs (sample scenes, persons, and rooms) are only a starting seed; a connected user can replace all of it from the UI, and Start blank gives them a clean slate to do so.

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.

Glance — HA Dashboard

Clone this wiki locally