Add-on Installation
Home Assistant OS and Supervised users run the controller as an add-on. This is the preferred path when Home Assistant should manage the controller container, logs, startup, port mapping, and setup UI.
Home Assistant Container / Core
The add-on requires the Supervisor. On Home Assistant Container or Core, run the controller as a standalone Docker container instead.
1. Add the repository
Or manually: open Settings → Add-ons → Add-on Store, open Repositories from the top-right menu, and add:
https://github.com/hyungyunlim/immich-ha-sa2. Install the add-on
Find Immich Frame Controller in the store and install it.
3. Configure
| Option | Required | Description |
|---|---|---|
immich_internal_url | yes | Immich API URL reachable from the add-on container |
immich_api_key | yes | Immich API key |
kiosk_internal_url | yes | immich-kiosk URL reachable from the add-on container |
kiosk_password | no | Set if your immich-kiosk uses KIOSK_PASSWORD |
local_public_controller_url | yes | URL that Home Assistant and the frame can reach on the LAN, usually http://<home-assistant-host>:8082 |
local_public_kiosk_url | yes | Browser-facing immich-kiosk URL on the LAN |
external_public_controller_url | no | Public controller URL for remote frames |
external_public_kiosk_url | no | Public immich-kiosk URL for remote frames |
default_frame_id | yes | Device ID of the default frame (default lenovo) |
default_frame_name | yes | Display name of the default frame |
default_network_mode | yes | auto, local, or external |
poll_interval_seconds | yes | Frame polling fallback interval (5–300) |
album_refresh_interval_seconds | yes | How often the controller refreshes Immich albums in the background; 0 disables automatic refresh |
controller_api_token | no | Optional static API token; most users should leave it blank and use pairing |
mqtt_broker_url | no | MQTT broker for FreeKiosk push control; leave blank to auto-detect the Mosquitto add-on |
mqtt_username, mqtt_password | no | Broker credentials; auto-filled from the Mosquitto add-on when the broker is auto-detected |
mqtt_base_topic | no | FreeKiosk base topic; leave blank for the default freekiosk |
MQTT is optional and auto-detected
Install the Mosquitto broker add-on and the controller connects to it automatically — no mqtt_* options needed. MQTT adds push hardware control, device presence, and live telemetry for FreeKiosk frames; without it the controller works exactly as before. See FreeKiosk.
4. Start and verify
Start the add-on, then open the add-on Web UI (ingress) or:
http://<home-assistant-host>:8082/setupYou should see the controller setup console with the default device and a pairing code.
Changing the port
The add-on exposes container port 8080 as host port 8082 by default. If you change the add-on network port, update local_public_controller_url, the integration's controller URL, and the frame's fixed URL to match.