User Guides

Features, workflows, commands, and everyday operation of the Heron dashboard and CLI.

The dashboard

Open heron.local in any browser on your Wi-Fi. The dashboard auto-discovers the device and shows your network activity. There is no account, no login, and no sticker code - LAN discovery is sufficient.

Routes

Route	Shows
`/` Monitor	Live network traffic, recent DNS events, device activity
`/manage`	Tracked devices, inline rename, device details
`/allowlist`	Allowlist patterns that suppress alerts

Connection banner

The banner at the top shows the device status: green when connected, yellow while searching, red when offline. If mDNS fails, enter the device IP manually - find it in your router's connected-devices list and use http://<IP>:8080.

Renaming a device

Click any device card on the Manage page to rename it inline. Custom names persist to /names.json on flash and survive reboots. Maximum 32 characters.

Allowlist

The allowlist suppresses alerts for domains you trust. Patterns are glob-style - *.telemetry.microsoft.com matches any subdomain. Add and remove entries from the Allowlist page.

The CLI

A terminal client heron talks to the same HTTP API as the dashboard and adds capabilities the web UI cannot offer: per-device live streams, snapshot-based change detection, exit-code monitoring for cron jobs, and JSON output for piping to other tools.

Install

pip install ./heron-cli

Python 3.8+ standard library only. Zero external dependencies.

Commands

Command	Description
`heron`	Pretty summary: stats grid, devices, recent activity
`heron report --table`	Compact table format
`heron report --json`	Raw JSON output, pipeable to `jq`
`heron report --compact`	One-line status
`heron report --scope devices`	Devices only (also: `stats`, `activity`, `all`)
`heron watch`	Live refresh every 5 seconds
`heron follow <ip>`	Live DNS query stream from a single device
`heron diff`	What changed since the last run (snapshot-based)
`heron monitor`	Silent check - exit 0 if OK, exit 1 if alert. For cron.
`heron allow add <pattern>`	Add an allowlist entry
`heron allow rm <id>`	Remove an allowlist entry
`heron allow ls`	List allowlist entries
`heron debug`	Raw `/debug` dump
`heron --host <ip>`	Manual device IP, skips mDNS

State files

~/.heron-host - last Heron device IP
~/.heron-snapshot - JSON snapshot, shared by diff and monitor

The OLED display

The on-device OLED alternates between two views: query count and KB transferred, then Wi-Fi signal percentage and uptime. The display is active only after provisioning - it is intentionally skipped during USB setup to keep the serial loop fast.

Alerts

The buzzer sounds when the DNS classifier flags a query - either a flagged-domain match or a new-connection event. The dashboard shows flagged events in the activity feed. The allowlist suppresses buzzer and dashboard alerts for trusted patterns.

Clearing the log

The DNS log is cached to /dnslog.json on flash. Clear it from the dashboard or by resetting the device. There is no remote wipe, because there is no remote connection.