Your first app in 15 minutes
Generate an OpenNVR app from the SDK, write the rule, prove it with the generated tests — no camera and no Docker — then run it against your stack and decide whether to list it in the catalog or keep it private.
On this page
By the end you’ll have a real OpenNVR app: generated by the SDK, a rule you wrote, tests passing, and running against your stack. Steps 1–3 need no camera and no Docker.
You need Python 3.11+ and
uv(orpip). A running OpenNVR stack is only needed for step 4.
The app you’ll build is a Detector: it listens to the detections OpenNVR already produces and decides when something is worth an alert. It runs no model of its own, so it costs no GPU.
1. Generate the app (1 min)
uvx --from opennvr-app-sdk opennvr-app new package-watch --task object_detection
cd package-watch
With pip instead: pip install opennvr-app-sdk then opennvr-app new package-watch --task object_detection.
package-watch is your app’s id. --task names the kind of AI it relies on — object_detection here — and any adapter that serves that task will satisfy it. You get a working app, not a template with holes:
package-watch/
├── package_watch.py manifest, config, THE RULE, command line
├── config.example.yml what an operator configures
├── pyproject.toml the SDK pinned from PyPI, plus a dev group
├── Dockerfile builds from PyPI alone
├── README.md
└── tests/test_smoke.py proves the app is wired to the SDK
2. Write the rule (5 min)
Everything except the rule is handled by the SDK: subscribing to the event bus, decoding detections, isolating errors, sending alerts, the command line. Your part is one method in package_watch.py:
def on_detections(self, camera_id, detections, event) -> list[Alert]:
"""THE RULE. Return the alerts to fire; return [] to stay quiet."""
# Each detection: {"label", "confidence", "bbox": {"x","y","w","h"}, "track_id", ...}
# bbox is normalised 0..1. The starter keeps the labels this app watches...
matches = [d for d in detections if isinstance(d, dict)
and str(d.get("label", "")).lower() in self.cfg.watch_labels]
if not matches:
return []
label = str(matches[0].get("label", "")).lower()
# ...and alerts on any sighting. Put your rule here.
return [Alert(
title=f"{label.capitalize()} seen on {camera_id}",
camera_id=camera_id,
severity="medium",
correlation_id=str(event.get("correlation_id") or ""),
evidence={"label": label, "confidence": matches[0].get("confidence")},
)]
Replace the starter with your rule. The SDK has the pieces most rules need:
| You want… | Use | Example to read |
|---|---|---|
| Only inside a drawn zone | opennvr_app_sdk.geometry.Zone |
loitering-detection |
| Only after someone stays a while | opennvr_app_sdk.state.keyed_state |
loitering-detection |
| Count in a zone, alert on a limit | an edge-triggered counter | occupancy-counting |
| The same object across frames | state keyed on track_id |
line-crossing |
| A confidence floor or a time window | plain Python | — |
Add settings as Param(...) entries in the manifest; the operator gets a form for each, generated from your declaration.
3. Prove it, with no camera (2 min)
uv sync
uv run pytest -q
uv run opennvr-app validate .
The generated test drives your app through the SDK’s real decode → rule → alert path with an in-memory recorder: a matching detection must fire exactly one alert. Extend it as your rule grows — a case below the threshold stays quiet, a case inside the zone fires. validate checks the manifest, example config and listing the way a reviewer would.
See it fire, with SDK 0.7.0:
opennvr-app devruns the app against a simulated camera, with no broker and no Docker, and shows each alert as it fires.--label,--cameraand--confidenceshape the simulated object.
4. Run it against your stack (5 min)
cp config.example.yml config.yml
# set nats_url, nats_token (your stack's INTERNAL_API_KEY) and watch_labels
uv run python package_watch.py --config config.yml --once
--once handles one event and exits — the quickest check that the wiring is right. Drop it to run continuously. No camera? Point a phone or a video file at the stack first.
To run it inside the stack and see it in the App Catalog, uncomment the contract_port / opennvr_url block in config.yml. On first registration the platform gives your app its own key, and from then on the SDK’s OpenNVR() client gives your rule the cameras picked for it, snapshots, past events and somewhere to keep state.
5. Keep it private, or list it
You do not have to publish anything. An app that runs from your own repository and your own registry works exactly like a catalog app, and the SDK is Apache-2.0, so it can be closed source.
To list it in the App Catalog every deployment opens, generate the repository files with opennvr-app new package-watch --repo, publish and sign the image, and open a pull request that adds one entry to the index. CONTRIBUTING_APPS.md walks through it.
One rule, two doors
Because your app declares the task it needs, it is also a skill the camera agent can use: “is anyone loitering by the shed?” reaches the same rule your catalog card runs. Write the rule once and both open.
Next
- Your first adapter — publish a model instead of a rule
- App SDK reference — every class and helper
- Ask on GitHub Discussions or Discord