frigate-top

htop for your Frigate NVR box — a real-time terminal dashboard for Frigate CCTV hosts

frigate-top is a real-time, interactive terminal dashboard for Frigate NVR/CCTV hosts — htop for your Frigate box. It shows host-level metrics (CPU, memory, disk I/O, network I/O + errors, NVIDIA GPU, CPU iowait, load) and Frigate-specific metrics (skipped frames, detector inference time, detection FPS, camera FPS, online/offline cameras, estimated supported cameras) across a grid of block-bar graphs (one GPU set per detected GPU). Each graph fills the full width over the configured timeframe, carries a -span … now time axis, colours its fill and current value green/amber/red by warn/crit thresholds, and marks the newest sample with a bright endpoint.

It is stdlib-only Python in a single file — no pip, no required dependencies, no build step.

_{The dashboard — SYSTEM / NETWORK / FRIGATE bands, live block-bar graphs, and a boxed header table.}

What it does

• Draws a live, auto-refreshing dashboard grouped into SYSTEM / NETWORK / FRIGATE bands with colour-coded graph borders (blue = system, yellow = network, orange = Frigate).
• Shows a header table grouped into identity (hostname, uptime, OS, kernel), hardware (CPU, memory, GPU model + driver), Frigate (version, camera counts, supported-camera estimate, detector), and streams/storage (resolution, retention, interface, disk) — plus a status line of active warnings.
• Summarises tracked-object activity for the selected timeframe in the header (Detections 1m 4 person 2 vehicle 1 animal 2 face 1 plate), pulled from /api/events — a fixed category breakdown (person / vehicle / animal / recognised face / recognised plate, plus other) so the structure is visible even at zero. The API is polled at most every few seconds and cached.
• Collapsible sections — press s / w / f to fold the System / Network / Frigate groups; System and Network start collapsed so everything fits smaller terminals. Handles live terminal resizing without dropping graphs.
• Detects multiple GPUs and draws a labelled GPU0 / GPU1 … util/mem/temp set for each.
• Graphs Frigate skipped frames and NET errors in red on any nonzero value — these should always be zero, so they catch the eye immediately.
• Renders block-bar graphs by default (--braille for dense Braille area charts, --ascii for plain ASCII). Fills always span the full width and scroll left over the true timeframe; the x-axis reports how much history is currently shown.
• Encodes health in colour: bars and the title value turn amber past the warn threshold and red past crit, with a dashed guide line at each threshold and a ▲/▼/→ trend arrow versus the window start.
• Marks absent sensors (no GPU, no Frigate) with a dimmed no sensor panel instead of a misleading flat line.
• Estimates how many cameras the detector(s) can keep up with — a throughput bound (detector inferences/sec × headroom ÷ configured detect fps), which is the real limit on a Frigate box. It is motion-independent (uses the configured detect fps, not the noisy live rate); a single Coral at 5 fps works out to ~18 cameras. Tune the safety margin with --detector-headroom (default 0.75).
• Auto-detects the Frigate API at common ports (5000, 8971, 80, 443) and protocols (HTTP/HTTPS) (override with --frigate-url); tracks disk and the busiest network interface (pin with --disk / --net-iface).
• Lets you switch history timeframe on the fly (1, 5, p for 15m, t for custom) and export samples to CSV (--csv).

Install

frigate-top is a single stdlib-only module, so the simplest install is the file itself — no pip, no dependencies, and it sidesteps the externally-managed-environment (PEP 668) error on modern Debian/Ubuntu entirely.

Single file — recommended (no pip, no dependencies):

# fetch the release file and drop it on PATH
sudo curl -fsSL https://git.jdneer.com/jd/frigate-top/raw/tag/v1.1.0/frigate_top.py \
  -o /usr/local/bin/frigate-top
sudo chmod +x /usr/local/bin/frigate-top
frigate-top

It carries a #!/usr/bin/env python3 shebang and needs only Python 3.7+ and the standard library. (Optional: apt install python3-yaml for richer Frigate config parsing — a regex fallback is used without it.) Swap raw/tag/v1.1.0 for raw/branch/main to track the latest, or just scp frigate_top.py user@host:/usr/local/bin/frigate-top if you already have a clone.

As a managed command with pipx (isolated venv, PEP 668-friendly):

sudo apt install pipx          # if not already present
PIP_INDEX_URL=https://git.jdneer.com/api/packages/jd/pypi/simple/ pipx install frigate-top

From the Forgejo package registry with pip:

pip install --index-url https://git.jdneer.com/api/packages/jd/pypi/simple/ frigate-top
# optional extra for richer YAML config parsing:
pip install --index-url https://git.jdneer.com/api/packages/jd/pypi/simple/ 'frigate-top[yaml]'

On a PEP 668 system (recent Debian/Ubuntu), pip won't touch the system Python — use the single file or pipx above, install into a python3 -m venv first, or append --break-system-packages if you accept the consequences.

From source:

git clone https://git.jdneer.com/jd/frigate-top.git
cd frigate-top
pip install .          # or: pip install '.[yaml]'

Usage

Run frigate-top (installed) or python3 frigate_top.py (single file).

Controls (keyboard):

• m — toggle memory graph between percentage and bytes (used / cached / free)
• n — toggle network graphs between Mbps and MB/s
• s / w / f — collapse or expand the System / Network / Frigate sections (System and Network start collapsed)
• 1 / 5 / p — set history to 1 / 5 / 15 minutes
• t — set a custom history timeframe (in minutes)
• q — quit

Examples:

# Default 1-minute history, 1-second refresh
frigate-top

# 10-minute history
frigate-top --timeframe 10

# Point to a Frigate API and config
frigate-top --frigate-url http://localhost:5000 --config /config/config.yml

# Pin a specific network interface / disk device
frigate-top --net-iface eth0 --disk nvme0n1

# Write samples to CSV
frigate-top --csv /tmp/frigate-top.csv

# Dense Braille area charts, or plain ASCII with no colour
frigate-top --braille
frigate-top --ascii --no-color

# One-off snapshot for cron or health checks (works headless)
frigate-top --snapshot

Requirements

• Python 3.7+ (Linux — reads /proc and /sys)
• No required dependencies. frigate-top runs on the standard library alone.
• Optional, detected at runtime:
  • PyYAML (frigate-top[yaml]) — richer Frigate config parsing; a minimal regex fallback is used without it
  • nvidia-smi — NVIDIA GPU stats
  • docker or podman — Frigate container status
  • A reachable Frigate API — camera/detector stats and the detections summary

Configuration

All options can be set via command-line arguments or environment variables.

Variable	Default	Description
TIMEFRAME	1	Graph history in minutes
REFRESH	1.0	Refresh interval in seconds
MAX_TIMEFRAME	60	Maximum allowed history in minutes
FRIGATE_CONFIG	""	Path to Frigate config.yml
FRIGATE_URL	""	Frigate API URL, e.g. http://localhost:5000
INSECURE	0	Set to 1 to skip TLS verification for a remote HTTPS Frigate (loopback always allowed)
NET_IFACE	""	Network interface to monitor (auto-detected if empty)
DISK_DEVICE	""	Disk device to monitor, e.g. sda / nvme0n1 (auto-detected if empty)
CSV_FILE	""	Append samples to CSV
ASCII	0	Set to 1 for ASCII graph characters
BRAILLE	0	Set to 1 for dense Braille area charts instead of block bars
NO_COLOR	0	Set to 1 to disable colors
CPU_WARN	80	CPU warning threshold
CPU_CRIT	95	CPU critical threshold
MEM_WARN	80	Memory warning threshold
MEM_CRIT	95	Memory critical threshold
GPU_WARN	80	GPU utilization warning threshold
GPU_CRIT	95	GPU utilization critical threshold
GPU_TEMP_WARN	80	GPU temperature warning °C
DISK_IOWAIT_WARN	20	I/O wait warning threshold
DISK_FULL_CRIT	85	Storage full critical threshold
NET_WARN	1000	Network throughput warning Mbps
FRIGATE_SKIPPED_WARN	1.0	Skipped FPS warning threshold
FRIGATE_INFERENCE_WARN	100	Detector inference time warning ms
DETECTOR_HEADROOM	0.75	Fraction of detector throughput used to size the supported-cameras estimate

Files

File	Description
frigate_top.py	The dashboard — a single stdlib-only module
pyproject.toml	Package metadata (version read from __version__)
requirements.in / requirements.txt	Optional pinned + hash-verified PyYAML (see below)
VERSION.md / CHANGELOG.md	Versioning and release notes
LICENSE / NOTICE / DISCLAIMER.md	Apache-2.0 licence and terms

Optional supply-chain hardening

PyYAML is optional. If you want it hash-verified, requirements.txt pins it with SHA-256 hashes:

pip install --require-hashes -r requirements.txt

Regenerate after changing requirements.in:

pip install pip-tools && pip-compile --generate-hashes requirements.in -o requirements.txt

Versioning

frigate-top follows Semantic Versioning. The version lives once in frigate_top.py as __version__ and flows to the header title and the built package — see VERSION.md for the release process and CHANGELOG.md for history.

Notes

• If the terminal is too small or not a TTY, use --snapshot for a one-off reading.
• The first sample is used as a baseline and is not shown in the graphs, so deltas are meaningful.
• Frigate config auto-detection tries /config/config.yml, /config/config.yaml, /etc/frigate/config.yml, /opt/frigate/config/config.yml, and ~/frigate/config/config.yml.
• MQTT broker monitoring is intentionally not included because the broker is optional and containerized; the Frigate API provides the same health signals.
• Security posture: the tool is read-only — it shells out only to fixed commands (nvidia-smi, docker/podman ps, df) with no shell or user-interpolated arguments, parses YAML with safe_load, and writes its optional --debug log to a per-user directory ($XDG_RUNTIME_DIR) opened with O_NOFOLLOW. TLS certificates are verified for remote HTTPS Frigate instances; verification is relaxed only for loopback hosts (where self-signed certs are the norm) or when --insecure is passed.

License

Licensed under the Apache License 2.0. See NOTICE for attribution and DISCLAIMER.md for terms regarding use, third-party trademarks, warranty, and liability.

frigate-top is an independent project and is not affiliated with or endorsed by the Frigate NVR project, NVIDIA, Google, or Docker.