Projects
Preparing the portfolio shell before the interactive work loads.
Preparing the portfolio shell before the interactive work loads.
Network Monitor · Documentation
Build Network Monitor on an Apple Silicon Mac, configure your network targets, and verify that the local recorder is collecting evidence.
You need an Apple Silicon Mac running macOS 14 or later, Python 3.10 or later, and Apple’s Command Line Tools. This is an MIT-licensed source release that you build locally. A notarized installer is not provided.
The recorder uses Python’s standard library and macOS utilities. The dashboard uses SwiftUI and Charts. Keep the selected Python interpreter installed at a stable path: the background job uses that exact interpreter.
Install from the intended user’s logged-in session. Recording resumes after that user logs in following a reboot. It does not run before login, unlock FileVault or keep the Mac awake. No cloud account, API key or router password is required.
The probes were developed for an Orbi router behind an AT&T gateway. Router and gateway service checks expect TCP port 80, and the router DNS check expects a DNS service. Gateway web diagnostics understand supported AT&T status pages. Satellite identity checks currently expect Orbi RBE770; another model may answer ping or TCP while failing that identity check. These differences alone do not establish an outage.
Step 1
Run these commands in Terminal on the Mac you want to monitor.
git clone https://github.com/crispierry/home-network-monitor.git
cd home-network-monitor
cp config.json config.local.json
cp devices.example.json devices.local.json
scutil --get LocalHostNameEdit config.local.json before installing. The shipped 192.0.2.x addresses are documentation examples. Replace them with your confirmed local addresses.
| Setting | What to enter |
|---|---|
expected_host | This Mac’s LocalHostName, printed by the last command above. |
orbi | Your main router’s IPv4 address. |
gateway | Your upstream gateway’s IPv4 address. |
peer | Leave "" for one computer. |
satellites | Confirmed satellite IPv4 addresses, or []. |
speed_enabled | Leave false initially. |
Keep the other defaults unless your setup requires a deliberate change. An empty peer setting removes that check. A configured peer failing to reply does not establish an internet outage.
Edit devices.local.json with confirmed addresses, MAC identities and dated attachment notes. To start without device checks, set its contents to []. Attachment notes are a manual inventory, not a live association measurement. Both local files are ignored by Git; installed settings live outside the checkout.
Step 2
sh scripts/check.sh
python3 manage.py install --config config.local.json --devices devices.local.json
python3 scripts/build_macos.py --install
open "$HOME/Applications/Network Monitor.app"The check script uses synthetic data and sends no network probes. The installation command starts live recording. Allow the Network Monitor service Local Network access when macOS requests it.
The recorder is a per-user background job. Closing the dashboard leaves it running. Bandwidth tests stay disabled with the initial settings above.
Step 3
~/.local/bin/network-monitor status
python3 scripts/verify_install.py --compactConfirm the intended host and interface, service_running is true, the sample is less than three recording intervals old, and diagnostics_fresh is true. Check the installed-file, source and signature results, along with the expected inventory and schedule.
The verifier returns a nonzero status when installation or freshness checks fail. A network probe can fail while the recorder is working correctly. Compare those failures with the actual symptoms rather than treating them as installation failures.
Open Overview and confirm that the sample time, recorder status and version agree with the verifier. Verify a second observer on that Mac independently.
~/.local/bin/network-monitor query --hours 24This query reads saved evidence without starting probes or speed tests. A local agent can run the same command when it has local command access.
Install and verify independently on the second Mac. For an offline comparison, choose Evidence → Export snapshot…, transfer the file privately, then use Import snapshot… on the other Mac. Snapshots retain their original timestamps and do not update themselves.
Automatic sharing is disabled by default. It currently requires LocalHostNames Mini-One and Mini-Two on 10.0.0.0/24, with separate pairing and listener approval. Keep it disabled for other hosts or networks and use snapshots instead. The technical architecture explains the data flow; the repository’s sharing setup reference ↗ covers pairing. A one-Mac installation needs no sharing setup.
Choose these settings before the first installation if you want scheduled tests: set speed_enabled to true, select hours from 0 through 23 in speed_hours, and choose a speed_slot. Slot 0 can start from :15:30 in each selected hour; slot 1 from :45:30. Schedules use America/Los_Angeles, including daylight saving time. The next eligible recorder cycle starts the test; the exact second is not guaranteed.
These tests deliberately load the connection and can affect calls. Keep them outside meetings and reduce the schedule when the investigation ends. Changing only speed_hours on an installed recorder can preserve its checkpoint; apply those hours with python3 manage.py install --config config.local.json, using your current private configuration.
Changing speed_enabled or speed_slot changes the configuration fingerprint. Reinstalling that changed configuration against the old checkpoint is rejected. First stop monitoring through Monitoring & storage, preserve the evidence folder and installed settings privately, and move state.json out of the active ~/Library/Logs/NetworkMonitor folder into your private archive. Then install the explicit new configuration. Retain the old checkpoint to explain any open incident. A normal upgrade with unchanged settings does not require this baseline reset.
Quit the dashboard, then run these commands from the source checkout.
git pull --ff-only
python3 manage.py install
python3 scripts/build_macos.py --install
open "$HOME/Applications/Network Monitor.app"
python3 scripts/verify_install.py --compactOmitting configuration and device arguments preserves installed settings and inventory. Installation starts the recorder, including if it was paused. Keep the runtime’s separate service launcher; it is not an extra dashboard.
If the optional summary worker is installed, rerun python3 scripts/install_sync.py from the matching release checkout on both Macs and verify sharing separately. Preserve the existing Sync directory, which holds pairing and the enabled setting.
If evidence is stale, check python3 manage.py service-status, the Python path, login and sleep state, and the service log. If foreground LAN probes work but background probes fail, review Local Network permission for the service. Unsupported diagnostic pages remain unknown.
Use Monitoring & storage to stop or resume recording. To uninstall from the checkout, run python3 manage.py uninstall. This removes recorder and sync jobs and the CLI while retaining evidence. You can then move the dashboard to Trash. Preserve evidence you need before removing retained files.