Home Assistant
Connect OpenNVR to Home Assistant two ways: MQTT discovery with nothing to install, or the native integration from HACS with live video and a media browser. Every camera, zone and app appears as a device, scoped by an API token and audited.
On this page
OpenNVR works with Home Assistant two ways. MQTT discovery needs nothing installed in Home Assistant beyond its own MQTT integration: turn it on and Home Assistant lists one device for the OpenNVR server, one per camera, one per zone, and one per app that declares entities. The native integration, installed from HACS, gives the same devices plus live video, snapshots, a media browser and services. Use one or the other, not both.
This page is the short version. The full guide, with every entity and the raw MQTT topics, is HOME_ASSISTANT_USER_GUIDE.md; the network side (ports, WebRTC, RTSPS) is HOME_ASSISTANT.md.
What appears in Home Assistant
| Device | Entities |
|---|---|
| Server | CPU, memory and storage · unacknowledged alerts and the highest severity · Acknowledge all alerts · site mode as an alarm panel · Manual event |
| Each camera | online · motion · detection and recording switches · last object seen · last plate read · object counts per class · PTZ buttons and presets · an event entity that fires on every detection and alert |
| Each zone | occupancy and head-count per class |
| Each app | whatever the app declares: Occupancy’s counts and levels, Guard Scan’s compliance rate, and so on |
Diagnostics such as CPU, bitrate and inference time are created disabled; enable the ones you want.
Set it up
1. A broker. Any MQTT broker Home Assistant already uses, such as the Mosquitto add-on. OpenNVR must be able to reach it, and it should have a username and password: the broker is the trust boundary.
2. An API token in OpenNVR. Settings → API Tokens → New token. A new token starts with the Home Assistant scopes: see cameras, live view, recordings, alerts and system information. Add a scope for each thing Home Assistant should be allowed to do:
| Add | To get |
|---|---|
cameras.manage |
the detection and recording switches |
ptz.control |
PTZ buttons and presets |
settings.manage |
site mode as an alarm panel you can arm and disarm |
events.create |
the Manual event button |
You can limit the token to some cameras. Don’t limit it to an address: commands arrive from the broker, so an address-limited token can’t be used here.
3. The MQTT integration in OpenNVR. Settings → Integrations → Add → MQTT: the broker URL (mqtt://broker:1883, or mqtts://broker:8883 for TLS), its username and password, Home Assistant discovery on, and Act as API token set to the token from step 2. Leave the topic prefix opennvr and the discovery prefix homeassistant unless you changed them. Save.
4. Check. Within a few seconds, Settings → Devices & services → MQTT in Home Assistant shows OpenNVR and one device per camera.
Automations
A person at the front door after dark turns the porch light on:
automation:
- alias: Porch light on a person at night
trigger:
- platform: state
entity_id: event.front_door_detection
condition:
- condition: template
value_template: "{{ trigger.to_state.attributes.event_type == 'person' }}"
- condition: sun
after: sunset
action:
- service: light.turn_on
target: { entity_id: light.porch }
Arm OpenNVR when everyone leaves:
action:
- service: alarm_control_panel.alarm_arm_away
target: { entity_id: alarm_control_panel.opennvr_site_mode }
How it stays safe
- The token bounds everything. Home Assistant sees what the token may see and does only what it may do. Every command is written to OpenNVR’s audit log, attributed to the integration.
- Commands are not replayed. Retained messages never run a command, and commands are rate-limited.
- Revoking is immediate. Revoke the token and the devices go offline within a minute. Delete the integration and OpenNVR clears what it published.
- Secrets stay secret. The broker password is encrypted at rest and never returned by the API.
Troubleshooting
| Symptom | Fix |
|---|---|
| No devices appear | Home Assistant’s MQTT integration must use the same broker and discovery prefix. OpenNVR’s log names an unreachable broker, refused credentials or a revoked token on its MQTT bridge lines. |
| A camera is missing | The token can’t see that camera, or lacks cameras.view. |
| A switch or button does nothing | The token lacks the scope for it (see step 2). |
| Everything appears twice | An older Home Assistant Relay app is still enabled alongside discovery. Disable it in the App Catalog. |
| Entities go unavailable | The token was revoked or expired. Create a new one and select it in the integration. |
The native integration
The OpenNVR integration for Home Assistant adds live video over WebRTC, snapshots, a media browser for recordings and clips, services for PTZ, events and exports, phone notifications with the picture (a blueprint ships), and an Assist tool that answers “what’s on the driveway camera”. It needs Home Assistant 2026.9 or later.
1. HACS → Integrations → ⋮ → Custom repositories → add https://github.com/open-nvr/hass-opennvr, category Integration. Install OpenNVR and restart Home Assistant.
2. Settings → Devices & services → Add integration → OpenNVR. Enter https://<your-opennvr> and the API token from step 2 above. Turn off certificate verification unless you installed a trusted certificate; the integration raises a repair to remind you.
3. Choose the cameras. Leaving all selected means cameras added to OpenNVR later appear too.
If OpenNVR is also publishing MQTT discovery, the integration raises a repair: keep one path, or everything appears twice. Releases: hass-opennvr; its client library is pyopennvr on PyPI.
The story behind the design is on the blog: Home Assistant with nothing to install.