OpenVigil

A self-hosted NVR for IP cameras (Hikvision first, ONVIF second) that records everything locally, runs its own AI on your GPU and never talks to a cloud. One Docker stack, one install command.

Website: openvigil.dev · Română: README.ro.md · manual detaliat: docs/ro/manual.md

Status. Built for one real installation (18 Hikvision cameras, an NVIDIA RTX 2000 Ada, running 24/7 since mid-2026) and published as is, under AGPL-3.0. The interface is in English and Romanian; the code and its comments are in Romanian. It is a working system, not a product: expect rough edges outside the hardware it was built on, and read NOTICE.md for the licences of the models it downloads.

Screenshots

Taken on the built-in demo mode (synthetic cameras), so no real footage.

Live	Playback with timeline

HD view	Settings → Status

What it does

• Records continuously from every camera's main stream into 5-minute MP4 segments, with retention by days and by free disk space, motion-only mode per camera, and a chain of custody (SHA-256 per segment) for evidence.
• Streams live in the browser through go2rtc (MSE/WebRTC, two-way audio where the camera has a speaker), with an authenticated relay in front: go2rtc itself never listens on the LAN.
• Playback with a zoomable timeline, event markers, 0.5–8× speed (GPU), exports with burned-in boxes, time-lapse, heatmaps, region search.
• Local AI: YOLO11 detection (people, animals, vehicles, with fine-tuning on your own frames), face recognition, body re-identification, licence plates, natural-language descriptions (Qwen2.5-VL) and semantic search (SigLIP). All on the host GPU; CPU-only mode keeps detection and drops the heavy models.
• Operations: home/away/night modes with rules, Telegram alerts and a daily digest, Web Push, MQTT bridge (Home Assistant, Node-RED), webhooks, map view, siren/strobe/talk on supported cameras, camera health and tamper checks.
• Accounts: admin and per-camera viewers, 2FA (TOTP), revocable sessions, CSRF, strict CSP, audit log, public /verifica page to verify an exported clip by hash.
• Resilience: recorders fall back from go2rtc to the camera directly and come back on their own; nightly encrypted backup of configuration and databases; everything in data/ is plain files and SQLite you can read without the app.

Also in the box

• Ask in plain words: the search box answers questions like "when did the garbage truck come?" from the semantic index and the event log.
• Audio: continuous noise measurement on cameras with a microphone, hourly noise profiles to calibrate thresholds, noise alarms, and text-to-speech announcements through the camera's speaker.
• Incidents and cases: a triage panel (open / acknowledged / false alarm) with sound and pop-up on critical, and case files that bundle clips, snapshots and a signed manifest.
• Playback extras: bookmarks on recordings, several cameras played from the same moment, saved views and a wall mode for the live grid, an I/O panel for relays.
• Smarter events: presence episodes (one story instead of fifty frames), parked-vehicle episodes, new or missing object on static cameras, a second opinion with a stock model before an "intruder" alert, counting lines and zones pushed to the cameras as smart events.
• Training loop: a queue of uncertain frames, an annotation tool, a dataset built from your own cameras and fine-tuning from the UI, with per-model metrics.
• Operations: Telegram bot commands (/acasa, /plecat, /noapte, /stare), an automation API with its own token (/api/v1) for Node-RED or Home Assistant, forward-auth for other tools behind the same login, a camera clock check, a speed test that picks the playback resolution, stream quality per Hikvision camera, privacy masks, an archive tier that recompresses old recordings, coverage and continuity charts, and an installable PWA for the phone.

Why OpenVigil

• Your cameras, your disk, your GPU. Nothing leaves the house: no cloud account, no subscription, no licence per camera, no phone-home. Remote access is whatever reverse proxy you already trust.
• It works with the cameras you have. Hikvision over ISAPI (including siren, strobe, talk, PTZ and the camera's own settings from the same page) and anything that speaks ONVIF/RTSP. Adding a camera is a network scan and a click, not a config file.
• AI that goes past "a person was detected". Who it was (faces), the same person across cameras even without a face (re-ID), what happened in words (descriptions you can search), licence plates with known/unknown, and a detector you can fine-tune on your own frames from the interface.
• Built for evidence, not just viewing. Every segment has a SHA-256 in a chain of custody, every export is registered and can be verified on a public page without an account, and incidents go into case files you hand over as a ZIP.
• A complete system in one install. Modes (home/away/night) with rules, Telegram alerts and a daily digest, Web Push, MQTT and webhooks, accounts with per-camera roles and 2FA, audit log, health checks and self-healing recorders, nightly encrypted backups. One Docker stack, one script.
• Honest about what it is. Written for one real installation and published as is: it wants an NVIDIA GPU for the heavy models, it has one active author, and it will have rough edges on hardware it has not seen. Everything in data/ is plain files and SQLite, so you are never locked in.

Architecture

cameras (RTSP/ISAPI/ONVIF)
        │
        ▼
   ┌─────────┐  rtsp://127.0.0.1:8554/camN_main   ┌──────────┐
   │  go2rtc │ ─────────────────────────────────▶ │  record  │ ─▶ data/recordings/camN/*.mp4
   │ (host)  │                                    └──────────┘
   └────┬────┘   /api/ws (relay :STREAM_PORT)     ┌──────────┐
        └────────────────────────────────────────▶│   web    │ ◀── browser (:WEB_PORT)
                                                  │ Flask    │ ─▶ data/*.db, settings.json
                                                  └────┬─────┘
                                                       │ /detect, /faces, /describe (localhost)
                                                  ┌────▼─────┐
                                                  │    ai    │  YOLO11 · InsightFace · OSNet
                                                  │ (GPU)    │  Qwen2.5-VL · SigLIP
                                                  └──────────┘

All four containers share one image and the host network. Only WEB_PORT (UI) and 8555/udp+tcp (WebRTC media) are meant to be reachable from the LAN.

Requirements

• Linux host with Docker Engine and Compose v2. install.sh installs them on Ubuntu (22.04 or newer); on Debian and other distributions install Docker Engine with the Compose plugin from Docker's own repository first, then run the script.
• Disk for recordings: plan ~1 GB per camera per hour at 4 MP H.265, less with H.265+.
• Optional but recommended: an NVIDIA GPU with driver ≥ 580 (the image ships PyTorch for CUDA 13). install.sh installs nvidia-container-toolkit when it finds nvidia-smi. Without a GPU you get libx264 transcoding and CPU detection; faces, re-ID, descriptions and semantic search still run on the CPU but far too slowly to be useful, so turn them off.
• Cameras on a LAN the host can reach. Hikvision cameras need ISAPI enabled and an account with RTSP access; ONVIF cameras get live, recording, snapshots, PTZ and relays, but no siren, strobe, talk or event hooks.

Install

git clone https://github.com/sm26449/openvigil.git /opt/openvigil
cd /opt/openvigil
sudo ./install.sh

The script explains each step: Docker, GPU toolkit, .env (time zone, ports, data directory, the uid that owns the files), then pulls the published image (ghcr.io/sm26449/openvigil, about 11 GB: PyTorch with CUDA is most of it) and starts the stack. sudo ./install.sh --build builds the image locally from the checkout instead (~20 minutes, ~6 GB of wheels); that is also what happens automatically when PUID/PGID are not 1000, because the published image runs as 1000:1000. When the UI answers, open http://<server-ip>:8079, create the first account on /setup, then add cameras from Cameras → Add camera (there is a LAN scanner).

Everything you may want to change by hand is in .env (see .env.example). Everything else is set from the UI and lives in data/settings.json.

Day-to-day:

docker compose logs -f web            # add -f docker-compose.gpu.yml on GPU hosts
sudo ./install.sh --update            # git pull, pull the new image (or rebuild), restart
docker compose run --rm --no-deps web test      # pytest (350+ tests)

Language

The interface is available in English and Romanian. It follows the browser's language by default; every account can pin its own in My account → Language, and the login page has a switch (?lang=en). NVR_LANG in .env sets the server default, which is also the language of Telegram and e-mail notifications and of the daily digest.

Adding or adjusting a language needs no code: Romanian is the source text, so a dictionary is a flat JSON file mapping Romanian strings to translations. Drop data/i18n/<code>.json next to your recordings to override any string or add a language ({"_meta": {"nume": "Deutsch"}, "Adaugă camera": "Kamera hinzufügen", ...}); app/static/i18n/en.json is the complete reference and python3 scripts/i18n_check.py reports missing keys. Contributions of new languages are welcome.

Demo mode

No cameras yet? Settings → Tools → Demo mode adds four synthetic cameras (go2rtc generates the picture with ffmpeg's test sources). They stream, record and play back like real ones, so you can explore the interface, test an install, or take screenshots that show nobody's house. Remove them from the same card when you are done.

Reverse proxy and remote access

Keep the UI off the public internet; put it behind Traefik, Caddy or nginx with TLS and set in .env:

HTTPS=true
TRUSTED_PROXIES=127.0.0.0/8,::1/128,172.18.0.0/16   # loopback + the proxy's Docker subnet

TRUSTED_PROXIES must list only the addresses the proxy connects from: X-Forwarded-For and X-Forwarded-Proto are believed from those addresses alone (they drive the login rate limit, the audit log and the Secure cookie). The containers use the host network, so a LAN range here would let any LAN host spoof them.

The proxy must forward /api/ws and /api/frame.jpeg to STREAM_PORT (the video relay) and everything else to WEB_PORT. /api/auth/forward is a forward-auth endpoint if you want other internal tools behind the same login.

Data layout

data/
  recordings/camN/YYYY-MM-DD/HH-MM-SSZ.mp4   segments (UTC names)
  events.db, segmente.db, settings.json      journal, chain of custody, settings
  cameras.json, users.json, go2rtc.yaml      cameras (with passwords, mode 600), accounts
  faces/, plates/, reid/, dataset/, finetune/ AI data and training material
  backup/                                    nightly Fernet-encrypted backups (key in data/backup_key)
models/                                      Hugging Face cache (Qwen, SigLIP)

data/ is a bind mount: back it up, and if you want encryption at rest put it on a LUKS or fscrypt volume on the host. The app only notices when the directory is not writable.

Troubleshooting

• First build takes long / fails with "no space left": the image is ~11 GB and the build downloads ~6 GB of wheels. Keep 20 GB free on the Docker data root (docker system df).
• hwaccel GPU (h264_nvenc): NU in the web log, or torch cuda: False: the containers don't see the GPU. Check nvidia-smi on the host, then docker info | grep -i runtimes must list nvidia; rerun sudo ./install.sh to install the toolkit, and make sure you start the stack with -f docker-compose.gpu.yml.
• Yellow banner "the recordings directory is not writable": the DATA_DIR on the host is not writable by PUID:PGID from .env (chown), or the volume is read-only.
• Port already in use: change WEB_PORT, STREAM_PORT, AI_PORT, WEBRTC_PORT or the go2rtc addresses in .env, then docker compose up -d.
• Camera added but black tile / 502 thumbnail: the host can't reach the camera's RTSP (port 554) or the credentials lack RTSP rights; docker compose logs go2rtc shows the dial error. Hikvision cameras also need ISAPI enabled for events, siren and talk.
• AI features missing: faces, descriptions and semantic search need the GPU profile; on CPU only detection runs. Re-ID needs the OSNet ONNX file (see NOTICE.md).
• Logs: docker compose logs -f web record ai go2rtc; passwords never appear in them.

Day-to-day operations (logs, updates, backups, ports, uninstall): docs/operare.md (Romanian).

Tests

• tests/test_*.py: unit and API tests. Run inside the image with docker compose run --rm --no-deps web test, or on a plain machine with pip install -r requirements-ci.txt && python -m pytest -q tests (the AI-dependent tests skip themselves). This is what CI runs on every push.
• tests/ui-test.js: a Playwright walk through the real UI (needs a running stack and NVR_TEST_USER / NVR_TEST_PASS for an admin account of a test installation).
• scripts/module_check.py: static check of the ES modules.

Documentation

• docs/ro/manual.md: the decision log, in Romanian, written while the system was built for its original installation. Some sections describe the pre-Docker setup (systemd services, host encryption) and no longer apply as is.
• docs/nvr-ai.md, docs/ai-contract.md: the AI service and the web ↔ ai contract.
• docs/node-red.md: webhooks and MQTT with an example flow.
• SECURITY.md, CONTRIBUTING.md, NOTICE.md.

Licence

AGPL-3.0, see LICENSE. Third-party components and model licences are listed in NOTICE.md. Two of the models it downloads are licensed for non-commercial use only: the InsightFace face models and Qwen2.5-VL-3B (descriptions). A commercial deployment has to disable faces and descriptions or obtain licences from their authors. Not affiliated with Hikvision, NVIDIA or ONVIF.

Legal notice. OpenVigil can perform face recognition, person re-identification and licence-plate reading. These features process personal and, for faces, biometric data. You are solely responsible for using them lawfully on your own premises under the laws that apply to you: for example the GDPR in the EU (biometric data, lawful basis, data-subject rights), national video-surveillance rules and the obligation to signpost monitored areas. The software is provided "as is", without warranty of any kind and without liability for damages, as stated in sections 15 and 16 of the AGPL-3.0.

Credits

OpenVigil was built by Stefan Maldaianu (@sm26449), who designed it around his own installation and runs it every day, together with Claude (Anthropic's Claude Fable 5.1), which wrote most of the code in pair-programming sessions that Stefan directed, tested on real hardware and reviewed. Contact: [email protected].