open-nvr

The open platform for AI on your cameras: a self-hosted NVR (ONVIF/RTSP, recording, WebRTC) running any AI model through one open contract, with an app SDK and one-click apps. New capabilities arrive as software, not new boxes. Air-gapped or connected, audited end to end. Home Assistant built in. AGPLv3. A Frigate/Zone

Automatically checked · GitHub checked 2026-11-14

open-nvr

Overview

OpenNVR

Your cameras. Your hardware. Your AI. Your audit.

The open platform for AI on your cameras — new capabilities arrive as software, not new boxes.

OpenNVR is open-source video infrastructure for organisations and people who cannot hand their cameras to a vendor. It records and streams like any NVR, puts any AI model you choose behind the cameras, ships ready-made applications, and lets you write your own — on hardware you own, air-gapped if you need, with every inference audited.

CI Release License: AGPL v3 Python DOI

App SDK on PyPI Adapter SDK on PyPI Docker Home Assistant Discord

▶ Install walkthrough (video) · ⚡ Get it running · 🧩 Write an adapter · 📱 Write an app · 🏛 Government brief · 🔒 Security · 💬 Discord


OpenNVR screens: dashboard, live view with detection boxes, natural-language search, the App Catalog, and the Vehicles (ANPR) page

Dashboard · Live view · Search · App Catalog · Vehicles (ANPR). The dark and light variants follow your GitHub theme.


📖 Contents

✨ Why OpenNVR

📷 Any camera

ONVIF and RTSP cameras from any vendor, an Android phone, or the machine's own webcam.

🧠 Any AI model

One open contract: swap the detector, add plate reading or a vision-language model, and nothing else changes.

🏠 Local by default

Recording, AI and the assistant run on your hardware. Cloud models are opt-in and audited.

🔒 Ready for air-gapped sites

And for what still reaches them. Runs fully offline, can keep the cameras on a network with no route out, and traces every alert to the model weights that produced it.

🏡 Works with Home Assistant

Cameras, zones and apps appear as devices through MQTT discovery, with nothing to install in Home Assistant.

🛠️ Build AI applications

Two Apache-2.0 SDKs: an app is your rule on the platform's events, an adapter is your model behind the contract. Your first app · your first adapter.

⚡ Get it running

Two commands. You need Docker, nothing else (on Linux the installer offers to install it). No account, no API key, no cloud.

git clone https://github.com/open-nvr/open-nvr.git && cd open-nvr
./start.sh          # Windows: .\start.ps1
StepWhat happens
1. Answer the wizardEvery question has a working default in [brackets], so Enter through all of them gives a running stack. It generates the secrets, pulls the images, and prints your URL and a one-time setup token.
2. Open the URLAccept the self-signed certificate and paste the token.
3. Add a cameraDetection overlays appear within about 30 seconds.

[!NOTE] First run takes 8–15 minutes, almost all of it downloading images. Every start after that is seconds.

[!TIP] No camera to hand? OpenNVR Cam turns an Android phone into an ONVIF camera, or let the agent use the machine's own webcam.

Day-two commands
SituationCommand
Start now, no prompt./start.sh up
Re-print the setup token./start.sh token
Change settings or swap the example./start.sh reconfigure
Your LAN IP changed./start.sh refresh-certs (Linux/macOS)
Stop everything./start.sh down
Tail live logs./start.sh logs
Add an overlay or profile (fake cameras, an app)set OPENNVR_EXAMPLE_COMPOSE / OPENNVR_EXAMPLE_PROFILE in .env, then ./start.sh up — not docker compose -f … by hand, which drops the hardware flavour
Reclaim disk after upgrades./start.sh prune
Remove OpenNVR from this machine: apps, database, footage and all./start.sh uninstall (shows the plan, then asks you to type the confirmation sentence, which it draws on the screen rather than printing it, so it cannot be copied from there; --dry-run to look first; other stacks on the machine are never touched)
Upgrade to a new releaseback up, check out the tag, set CORE_TAG/ADAPTER_TAG, ./start.sh up: step by step

Unattended installs: cp .env.example .env && ./scripts/generate-secrets.sh --write && ./start.sh up. Retention, hardening and every compose file: DOCKER_QUICKSTART.md.

🧭 What OpenNVR is

The NVR was built to record. Now recording is where it starts.

A traditional NVROpenNVR
Features are fixed the day you buy it.Features arrive as apps and models, installed in one click on the same box.
AI means the vendor's cloud or a new appliance.Runs any model on your hardware.
Asks you to trust the vendor.Shows you the audit log, the model fingerprints and the evidence pack.

Three things in one install, each usable on its own.

📼A complete NVRONVIF and RTSP cameras in, recording and live view out, a detector always on. Works on day one with no AI configured at all.
🧠An AI platform for camerasAny model behind a REST or WebSocket endpoint becomes a capability through a published contract. Object detection, plates, faces, pose, scene description, open-vocabulary search, tracking, speech in and out all ship. Twelve installable applications sit on top: intrusion, loitering, occupancy, line crossing, plates, a doorbell that knows your family, a guard-scan check, a gate controller, and an agent you can talk to.
🛠️A product you build onTwo Apache-2.0 SDKs on PyPI. Write a server-side application or an adapter for your own model in an afternoon, run it on your own site, keep it private or publish it. The platform supplies cameras, streams, recording, detections, an event store with evidence, alerts, auth and audit. You supply the rule.
pip install opennvr-app-sdk        # write an application: your rule on the platform's events
pip install opennvr-adapter-sdk    # write an adapter: your model as a first-class capability

🛡️ Why organisations that cannot outsource trust run it

Governments, defence, critical infrastructure, healthcare and schools share one constraint: the footage, the models and the decisions must stay inside the perimeter and be explainable afterwards. Most camera software is built the other way round, with the vendor's cloud holding the keys. OpenNVR is built for the constraint.

The guaranteeHow OpenNVR keeps it
🚪Nothing leaves unless you open the doorTwo independent default-deny gates, DEPLOYMENT_MODE=offline and AI_SOVEREIGNTY=local_only, return HTTP 403 to every cloud route and every non-local model until an operator opts in. Apps reach the outside world only through an egress proxy on an allowlist an administrator approved.
🧱Offline is one door, not all of themAir-gapped systems are still reached by USB sticks, contractor laptops, insiders, tampered models and plug-ins that phone home. Per-camera permissions, MFA and an append-only audit log answer the first three; fingerprinted models with declared permissions the fourth; a credential per app and an egress allowlist the last.
🌑The camera network can stay darkIn dual-NIC mode, offered by start.sh and laid out in the reference appliance, the cameras sit behind one network card with no gateway and no route out, and operators, the phone app, alerts and updates reach OpenNVR on the other. The installer can add a firewall rule that drops forwarding between the two. Camera credentials are encrypted at rest, and video leaves the host only over RTSPS.
🔏You can prove which model made every decisionEvery model registers with the SHA-256 of its weights, re-checked every minute: a change raises a critical alert and an audit entry, and a model that asks for a new permission stops serving until an operator approves it again. One correlation id runs from the alert, through the gateway, to the model and the exact weights that answered.
📋Procurement can check itA §889 covered-vendor self-check is built in. The architecture is a peer-citable paper (DOI 10.5281/zenodo.22804254); this repository is its reference implementation.
🤫The sensitive part can stay sensitiveFine-tuned weights you cannot share, detection logic that is itself operationally sensitive, adapters under a classified licence: the Apache-2.0 SDK lets them run on the platform without ever being published.
Two things worth reading before you rely on those guarantees

Connecting the management side is a mode, not a downgrade. The management side can stay sealed or reach the internet for remote viewing over a VPN, phone alerts and updates; the camera side stays exactly as dark and every default-deny gate stays on. Online, the box itself is what the internet can see, so keep it behind your firewall and never port-forward it.

What a fingerprint proves, and what it does not. A hash proves the weights did not change after you approved them, not that they were clean when you did; that is what declared permissions, the default-deny network policy and fine-tuning on your own footage are for.

Read next
🏛 docs/GOVERNMENT_DEPLOYMENT.mdThe procurement brief
🔒 docs/SECURITY_ARCHITECTURE.mdThe control-by-control threat model
📑 docs/COMPLIANCE.mdThe evidence pack mapping

💾 Buy the hardware once

AI capability is arriving faster than any hardware refresh cycle. A camera system that needs a new appliance for each new capability will always be a generation behind. In OpenNVR a new capability is software.

A new capability is software, not a new box. A new model is released; it becomes an adapter on your existing OpenNVR box, where its weights are fingerprinted, its permissions declared and the local-only policy applied; an app in the App Catalog is installed and puts it to work; your people get the result as an alert on their phone. Recording runs the whole time, and a new appliance is crossed out.

A new model, an adapter, an app, an alert, on the box you already have. The fall-alert app is an illustration; the other tiles are apps that ship today.

  • 🔁 A new model is an adapter, not a device. Swap the detector, add plate reading, add a vision-language model, upgrade to this month's weights: each is a container registered with the gateway, hot-swappable and fingerprint-tracked, on the box you already have.
  • 🪶 The always-on detector is deliberately cheap. Tier-0 scans the camera's substream at a low frame rate and wakes the expensive models only when something is worth a closer look. That gate is why a mini-PC carries a whole site: the heavy models run on seconds of footage per hour, not all of it.
  • 📐 It adapts to the box it finds. A smaller machine runs the same software with the heavier capabilities switched off; turning one on is a decision, never a surprise.

What runs comfortably where

Your hardwareWhat's comfortable
🍓 Raspberry Pi 4/5, 4 GBRecording, streaming, Tier-0 detection, zone / line / dwell apps
📦 Mini-PC, 8–16 GBAll of the above, plus plates, faces, the text camera agent
🖥️ Desktop or server with an NVIDIA GPUEverything, plus scene captioning, VQA, the hands-free voice agent
🍎 Apple SiliconAs above, with the LLM on the host via Metal

[!TIP] Detection using too much CPU is almost always video decode, not the model. Store the camera's substream URL, check DETECT_FPS, attach a hardware decoder with DETECT_HWACCEL. The full strategy is docs/DETECT_CPU.md.

Runs on what you have

The same images come in hardware flavours. One line in .env, OPENNVR_ACCEL=auto, picks the flavour from the hardware it finds, and every fallback to CPU is logged and exported rather than silent.

FlavourHardwareWhat it accelerates
plain CPUx86-64 and arm64Everything runs on the CPU
-intelIntel iGPU and NPUThe iGPU decodes the cameras and the Tier-0 detector runs on the NPU or iGPU through OpenVINO
-qualcommDragonwing and Snapdragon boardsThe detector runs on the Hexagon NPU through the ONNX Runtime QNN plugin. Measured: sixteen cameras at 2 fps on an Arduino Ventuno Q where the CPU managed four. The captioner, the camera agent's LLM, speech to text and search's embedder run on the same NPU. Boards and support from Indus Technologies.
NVIDIA—Next

The support matrix and benchmark protocol are in docs/HARDWARE.md. Make or own hardware we have not measured? Lend it to us or give us remote access and we port, benchmark and publish the numbers, good or bad.

🧱 Built to scale, built to be built on

Every part is its own service. Core, the media server, the message bus, the AI gateway, the detect pipeline, each adapter and each app run as separate containers that talk over NATS and HTTP. Compose is what ships; the service boundaries are what let you run the same images under any orchestrator and add replicas where the load is. Need more plate OCR throughput? Run more OCR adapters; the gateway registers each one and queues fairly per camera.

Writing your own is the normal path, not the advanced one.

📱 Write an appopennvr-app new my-app, edit one method, run the tests, point it at the stack. Your first detector in 15 minutes. The rules that keep an app cheap on the box: Building efficient apps.
🧩 Write an adapterAn adapter is about thirty lines around your model. Write your own adapter.
🎁 Publishing is optionalAn app or adapter you write runs on your site with no obligation to list it anywhere. If you do list it in the App Catalog, you keep the copyright, your name is on the card, OpenNVR takes no fee, and you can sell what the code needs through the built-in licence hook. The deal for developers.
🎯 Fine-tune what shipsEvery reference model is a swap away from your own weights: point the adapter at your fine-tune, or train one and keep it private. Not accurate enough on your site and no time to train? We fine-tune it on your footage, on your hardware.

🔌 How it fits together

Your cameras feed Records (always on, never gated), then Watches (a cheap always-on detector), then Events (one bus everything listens to), then Apps and the assistant. Watches asks KAI-C, the socket, for a task. A model adapter plugs into KAI-C and is checked (weights fingerprint, declared permissions, local-only policy) before it is trusted. The animation unplugs YOLOv8 and plugs in your own model: the AI wire pauses while recording continues, the new adapter is verified, then serving resumes.
📼 Records never depends on AIFootage is written in one-minute chunks whatever the models are doing. In the animation the AI wire goes quiet while a model is swapped and recording carries on. If every adapter on the box crashes, you still have the video.
👁️ Watches asks for a task, never for a modelThe always-on detector asks KAI-C, the socket, for object_detection. Whatever adapter is plugged in answers, and it is checked before it is trusted: weights fingerprint, declared permissions, the local-only policy. Swap YOLOv8 for your own fine-tuned model and nothing else on the wire changes.
⚖️ Adapters answer "what is it", apps decide "does it matter"An adapter reads a plate or recognises a face and says nothing about whether you should care. Apps hold the policy: this zone, these hours, that watchlist. Keeping them apart is what lets you swap a model without rewriting a rule, and write a rule without knowing which model is behind it.
🗂️ Everything worth remembering lands on one bus and in one storeEvents is the bus everything listens to. One row per visit, with its best frame and every claim the models made, carrying which model made it and how confident it was. The search page, the agent and any app you install next month all ask the same store, so they give the same answer.

The three-tier model, the wire contracts and the offline-first design are in docs/ARCHITECTURE.md.

🧩 Add a capability in one click

App Catalog in the sidebar lists the installable applications. Pick one, click Install, choose which cameras it watches. Each app declares what it needs before you install it, which cameras, which hosts it may reach, whether it wants a licence key, and an administrator approves that, so an app cannot quietly acquire access it never asked for. Cameras get jobs too: assign camera 1 to plates and cameras 2–3 to counting on each camera's settings page (how assignments work).

🚧 Perimeter and safety

ApplicationWhat it does
intrusion-detectionPeople in restricted zones during restricted hours
camera-tamperA camera covered, defocused, moved or frozen, with no model to run
gate-watchA gate left open, judged by one question to the vision model
garbage-dumpingGarbage dumped in a watched zone, found by open-vocabulary detection
ppe-checkA person missing required safety kit, judged from Tier-0's best crop by open-vocabulary detection
abandoned-objectUnattended items, with owner-proximity suppression
guard-scan-complianceWas every person wanded, and what did the scanner find

🚶 People and flow

ApplicationWhat it does
loitering-detectionDwell-time alerts on a live inference stream
occupancy-countingZone occupancy with over/under alerts
line-crossingDirectional tripwire and entry/exit counting

🚗 Vehicles and access

ApplicationWhat it does
license-plate-recognitionPlate reads, registers, watchlists, per-camera scan modes
gate-controllerOpen the barrier for allowed vehicles only

🚪 Doorstep

ApplicationWhat it does
smart-doorbellFace recognition with enrolment, strangers alerted with a photo
package-deliveryArrival, linger and pickup per parcel

🔎 Search, alerts and the assistant

ApplicationWhat it does
footage-search"Red truck at the dock yesterday" over recorded footage
alert-notifierWhat actually deserves to reach the guard's phone
camera-agentAsk your cameras questions, by voice or text, all local

Seventeen of the twenty shipped examples are listed above; inference-listener and alerts-subscriber are minimal subscriber templates, and home-assistant-relay is kept only as a NATS-to-MQTT bridge example now that Home Assistant support is built in. Every app is a copy-as-template starting point. Replace the predicate and you have a purpose-built NVR for your domain. Gallery and roadmap: examples/README.md, docs/ROADMAP.md.

OpenNVR also ships first-party apps whose source is not published, installed from the same App Catalog as a signed image: Attendly, attendance by face (classroom rosters, hostel and mess barriers, meal bookings, staff check-in). See docs/APP_LISTING_TERMS.md for how they are listed.

🏠 Works with Home Assistant

Turn on MQTT discovery and OpenNVR appears in Home Assistant's own MQTT integration, with nothing to install there.

📟 DevicesOne device for the server, one per camera, one per zone, and one per app that declares entities.
🎛️ EntitiesMotion, detection and recording switches, last object and last plate, object counts, PTZ buttons, the site mode as an alarm panel, and an event entity that fires on every detection and alert, ready for automations.
🔑 PermissionsEverything runs as an OpenNVR API token you choose. Home Assistant sees the cameras that token may see and can do only what it may do, and every command lands in the audit log.

Setup is four steps: the Home Assistant guide. The native integration, which adds live video, the media browser and phone notifications with the picture, installs from HACS: hass-opennvr.

🎙️ Talk to your cameras

The OpenNVR agent watches two cameras: a user asks about a plate, the agent searches history and answers; a monitored plate passes the road camera, the alarm automation fires and the agent speaks the alert
examples/camera-agent/quickstart.sh          # voice: click Start and speak
examples/camera-agent/quickstart.sh --chat   # chat: type and read

Open http://localhost:9100/demo. A local LLM does tool-calling over your live frames:

You askIt uses
"Is anyone in the kitchen?"A detector
"What's at the back gate?"A captioner
"Did a red truck come by the dock earlier?"The event store
"Who was at the door this morning?"Your face database

The brain is a dial, not a dependency: the bundled runtime, Ollama on the host where the GPU is, or any OpenAI-compatible endpoint you bring. Model picks and hardware notes: examples/camera-agent/README.md.

🛠️ Build on it

📱 An application subscribes to the platform's events and holds one rule:

pip install opennvr-app-sdk && opennvr-app new my-app   # scaffold, edit on_detections, uv run pytest

🧩 An adapter puts your model behind the contract:

from opennvr_adapter_sdk import AdapterApp, AdapterService, BodyShape, BODY_BYTES_KEY, InferResponse

class MyDetector(AdapterService):
    def load(self): ...                       # load your weights
    def is_ready(self) -> bool: return True
    def infer(self, payload) -> InferResponse:
        frame = payload[BODY_BYTES_KEY]       # ... your model ...
        return InferResponse(result={"detections": [...]})

app = AdapterApp(service=MyDetector(), name="my-detector", version="1.0.0",
                 vendor="me", license="MIT", tasks_advertised=["object_detection"],
                 body_shape=BodyShape.IMAGE).fastapi_app

Register the URL with the gateway and it is online: hot-swappable, audit-chained, fingerprint-tracked. Thirteen reference adapters and a one-command scaffold live in ai-adapter; the wire spec is docs/AI_ADAPTER_CONTRACT.md.

💡 Tell us the problem your cameras should solve

A camera system should make a site safer, more reliable and more productive, and it should be able to show its work. Most of what OpenNVR ships started as one organisation's specific problem: a jewellery showroom that had to prove every visitor was wanded, a society that wanted strangers' vehicles flagged and residents' waved through, a dock that wanted to search footage in plain words.

If you have a camera-based use case, describe it to us. We will tell you whether an existing app and adapter already solve it, whether a fine-tune of a shipped model gets you there, or whether it needs new work, and what that costs. Deployment assistance, adapter authoring under NDA, fine-tuning on your footage, compliance evidence packs and supported deployments are how the project is funded: [email protected]. The enterprise offer is in docs/ENTERPRISE.md.

⚖️ How it compares

Frigate is the right call for many homelabs, and we say so. OpenNVR solves a different problem: auditable AI surveillance with operator-controlled, sovereign AI.

OpenNVRFrigateZoneMinderVerkada
Self-hosted, runs air-gapped✅✅✅❌
Open adapter contract: any model, any licence, out of tree✅in-tree❌❌
Talk to your cameras, locally✅❌❌❌
End-to-end audit chain and model-drift detection✅❌❌❌
Default-deny sovereignty gates✅partial❌❌
§889 covered-vendor self-check✅❌❌❌

🤝 Community

The most valuable help, in order: build an app or adapter and tell us · follow the open-nvr organisation · star the repository.

📚 Documentation

📜 License and trademark

OpenNVR is dual-licensed.

PartLicenceWhat it means
The platform coreAGPL-3.0-or-laterFree forever, on any hardware, for anyone who honours the AGPL including its network clause.
The developer edges: the app SDK and the adapter SDKApache-2.0What you write can ship under any licence, including proprietary or classified.
What the AGPL does not coverOpenNVR Commercial LicensePre-installed hardware under your brand, embedding in proprietary software, hosted offerings without source disclosure, white-labelling.

Policy, decision matrix and FAQ: docs/LICENSING.md. Core contributions require a CLA; SDK contributions need a DCO sign-off.

"OpenNVR" and the logo are trademarks of the project; see TRADEMARK.md.


Cameras you connect. Hardware you own. AI you choose and author. Audit you can show.

⭐ Star on GitHub · 📄 Read the paper · ⚡ Get it running