Hardware sizing
Recording is a stream copy (no transcoding) and object detection runs only on motion snapshots, so Nightjar is lighter than transcoding NVRs. Rough guidance:
The main CPU costs are motion decoding (5 fps per camera, cheap on a substream, expensive on a 4K main stream) and the occasional YOLOX-tiny inference. Configure substreams — on small hardware it is the difference between comfortable and struggling.
Disk sizing
Continuous 1080p H.264 recording runs roughly 1–2 GB per hour per camera depending on bitrate; 2K/4K cameras more. Quick math for the default 14-day retention:
If the disk fills before
maxDays, the disk watermark (default 90%) prunes oldest footage first — the node degrades retention, never crashes the disk. Undersize the disk and you simply keep fewer days.
Troubleshooting
Camera won't connect
Camera won't connect
Test the RTSP URL from the node’s host before blaming Nightjar:Or open the URL in VLC (Media → Open Network Stream). If those fail, the URL, credentials, or camera network settings are wrong — check the brand patterns. Special characters in passwords must be URL-encoded (
@ → %40). Also confirm RTSP is enabled in the camera’s own settings, and use POST /api/cameras/{id}/probe to see the node’s view of the stream.No motion events
No motion events
Check, in order: the camera’s
detect flag is true; a substream URL is configured (or the main stream is decodable); and the motion actually crosses the trigger — more than 1.5% of the frame changing for 2 consecutive frames at 5 fps. Distant or tiny motion in a wide shot can stay under the threshold. Set LOG_LEVEL=debug and watch the logs for the motion decoder starting and for motion started lines.Events fire but stay kind 'motion'
Events fire but stay kind 'motion'
Object detection needs the model file. In Docker it is baked into the image; in local dev you must run
pnpm --filter @nightjar/node fetch-model once. If the model is missing the node logs a clear hint and detections are disabled — everything else keeps working. Also note detection only upgrades events when it scores ≥ 0.5 on the snapshot.Reading container logs
Reading container logs
http://<host>:1984 shows per-stream status and lets you test playback directly.Remote live view won't connect
Remote live view won't connect
Confirm the node shows cloud state
online in GET /api/status. If the node runs under Docker Desktop on macOS/Windows, WebRTC is degraded by design — use a Linux host. Some strict networks need a TURN relay; see Remote access.docker compose logs output.