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.