Home Assistant

Home Assistant is optional. Astrion can run on Harmony, IR or Apple TV alone. With it, the remote can show and control any entity, live.

The remote talks to Home Assistant directly, over its WebSocket API, with a long-lived token. Nothing goes through the cloud.

1. Create a token

In Home Assistant:

1. Click your profile (bottom left) › Security tab.
2. Under Long-lived access tokens, click Create token.
3. Name it after the remote, e.g. Astrion living room, and copy it now. It's only shown once.

🔒 The token works like a password: don't share it or paste it in dashboard.json. It stays on the remote and is not included in backups.

Which user?

• A normal user is enough to show and control entities.
• To use Home Assistant event hotkeys (astrion_button, see Hotkeys), the token must belong to an administrator. Home Assistant only lets administrators fire events. Without it, event hotkeys are refused (it's in the remote's logs) and everything else keeps working.

2. Connect the remote

On the remote's web page › Home Assistant › Connection settings:

Field	Example
URL	http://192.168.1.10:8123 or https://ha.example.com
Long-lived access token	the token from step 1
Webhook id (optional)	given by the Home Assistant integration, see below

Save. The remote reconnects in a few seconds. The bar at the top of the remote shows a banner while it isn't connected.

💡 For the first test, use Home Assistant's local IP address rather than a hostname. If the IP works and the name doesn't, it's a DNS issue on your network, not Astrion.

3. Add your devices

Still under Home Assistant, + Add device: pick a type, the entity, and a name, e.g. Living room TV.

The builder's card forms then offer these names instead of raw entity ids. Apple TVs paired directly appear in this list automatically.

The webhook (push)

By default, the Home Assistant integration asks the remote for its state from time to time. With a webhook id set on the remote, the remote tells Home Assistant as things happen instead:

• the page shown and the Activities started or stopped;
• the battery level and charging state;
• button presses set to Home Assistant event.

It is faster, and it saves battery: each poll wakes the remote's Wi-Fi, so with the webhook the integration polls only every 5 minutes instead of every 10 seconds.

Where to find the id: Home Assistant › Settings › Devices & services › Astrion Custom Dashboard › Configure. Copy the webhook id shown there into the remote's Webhook id field. (Remote 1.2.7+ and integration 2026.10.0+ for battery and button events.)

Battery: quiet mode while the screen is off

A busy Home Assistant sends hundreds of state changes per minute, and receiving them all night drains the remote. So, a little while after the screen goes off (30 s by default), the remote stops listening to state changes, and catches up instantly when the screen comes back on.

If something must keep reaching the remote with its screen off, list it in builder › 5. Standby & battery › Entities kept live while quiet. "Find my remote" doesn't need it. See Standby & battery.

Troubleshooting

Symptom	Check
"Auth failed — check token" banner	The token was revoked or mistyped: create a new one.
"Connecting…" or "Connection error — retrying" forever	The URL (http vs https, port 8123). Can the remote reach it? Try the IP. Is a reverse proxy blocking WebSockets?
Event hotkeys do nothing	The token's user must be an administrator. Check the logs at http://<remote-ip>:8080/logs.
Cards show stale values after waking	Normal for a second or two: the remote re-reads every state when the screen comes on.

See also: Home Assistant integration · Several remotes