Self-hosted local network monitor with 24-hour speed charts & sarcastic AI commentary delivered straight to Telegram.
A lightweight local bot that runs a speed test on your network every hour, scans active devices on your LAN using nmap
, and logs everything to a local SQLite database.
Every 4 hours, it delivers a detailed report complete with a 24-hour trend graph and a sarcastic, LLM-generated commentary on your network's behavior ("someone's hogging the bandwidth again").
Note
100% Private & Self-Hosted: No external metric servers involved — everything runs locally on your machine or Raspberry Pi. Only text reports and graph images are dispatched to your Telegram chat.
Every hour (SLEEP_TIME
in main.py
, default 3600 seconds):
Speed Test: Measures download/upload speeds, ping latency, ISP, and test server details usingspeedtest-cli
.LAN Scan: Scans the local subnet usingnmap
ARP scan to count active connected devices.Local Storage: Saves metrics & device tallies directly to a localmetrics.sql
SQLite database.Status Alert: Sends a concise status update to Telegram ("all good"or"line is dying").24h AI Report: Every 4th cycle (every 4h), generates a24-hour trend graph viamatplotlib
alongside a sarcastic LLM analysis of network load and speed fluctuations.
| Technology | Purpose |
|---|---|
Python 3.13+ (via uv ) |
|
| Core runtime | |
| SQLite | |
Local metrics persistence (metrics.sql ) |
|
speedtest-cli |
|
| Network bandwidth and ping measurements | |
nmap |
|
| Subnet ARP scanning for device discovery | |
matplotlib |
|
| 24-hour metrics visualization | |
| OpenAI-compatible API | |
| Sarcastic report & trend analysis (cloud OpenAI or a local LLM) | |
| Telegram API | |
| Alert and graph report delivery |
OS: macOS or Linux (nmap --iflist
required; Windows not supported out of the box).— manages the Python version, virtualenv, and locked dependencies for you. No manualuvpython3
/venv
/pip
juggling.System Binaries:nmap
andspeedtest-cli
installed system-wide.Passwordless— device counting needs a real ARP scan (raw sockets), which requires root; see one-time setup below.sudo
fornmap
Tokens: Telegram Bot Token, Telegram Chat ID, and an API key for your OpenAI-compatible provider (not needed if you pointAI_BASE_URL
at a local LLM server).
macOS (Homebrew):
brew install nmap speedtest-cli
Linux (Debian/Ubuntu):
sudo apt update && sudo apt install -y nmap speedtest-cli
Device counting runs nmap
as root for a real ARP scan — without it, host discovery silently falls back to ordinary TCP probing and undercounts devices that don't answer on common ports. Since the bot runs unattended, sudo
needs to work without a password prompt on every cycle:
echo "$(whoami) ALL=(root) NOPASSWD: $(command -v nmap)" | sudo tee /etc/sudoers.d/netmon-nmap
sudo chmod 440 /etc/sudoers.d/netmon-nmap
This grants passwordless sudo
only for the nmap
binary — not your whole account.
Install uv if you don't have it yet:
curl -LsSf https://astral.sh/uv/install.sh | sh
Then:
git clone https://github.com/Role1776/netmon.git
cd netmon
uv sync
uv sync
downloads the pinned Python version (see .python-version
) if you don't already have it, creates .venv
, and installs the exact locked dependency versions from uv.lock
. No system python3
, no manual venv activation.
Copy the template file and fill in your secrets:
cp .env.example .env
.env
variables:
| Variable | Description |
|---|---|
AI_API_KEY |
|
| Your LLM provider API key (any string works for most local servers) | |
AI_MODEL |
|
Model name (e.g. gpt-4o-mini , or a local model name — see below) |
|
AI_BASE_URL |
|
Base API URL (e.g., https://api.openai.com/v1 , or your local server's URL) |
|
TG_BOT_TOKEN |
|
Telegram bot token from @BotFather |
|
TG_CHAT_ID |
|
| Your Telegram Chat ID | |
DB_PATH |
|
SQLite database file path (e.g. metrics.sql ) |
Tip
You're not locked into OpenAI. ai.py
talks to any OpenAI-compatible endpoint, so a local inference server (e.g. Ollama, LM Studio) works too — just point AI_BASE_URL
at it. For report quality that holds up, use a model with at least ~7B parameters; a solid local pick is Gemma 4 12B at 4-bit (QAT) quantization (gemma4:12b-it-qat
via Ollama), which fits comfortably on 16GB of RAM.
uv run main.py
uv run
always uses this project's own .venv
and pinned Python version, so it can't accidentally run against your system python3
.
Tip
Run the bot inside tmux
/screen
or set it up as a system service (systemd
/launchd
) to keep it running 24/7 in the background.
Network Status Update
Time: 2026-07-21 14:00:00
ISP: MyISP | Server: New York
Devices online: 7
Download: 145.2 Mbps
Upload: 62.1 Mbps
Latency: 14.8 ms
Traffic used: 160.0 MB down / 70.0 MB up
Current status: Good speed and low latency
Every 4 hours, the bot sends a 24-hour matplotlib graph accompanied by a sarcastic LLM-generated report:
<b>Network Speed Test Report (24h Analysis)</b>
Client: <b>MyISP</b>
Server: <b>New York</b>
<b>Latest Test Metrics</b>
<pre>
Download: 178.5 Mbps
Upload: 45.2 Mbps
Ping: 23.1 ms
Devices Online: 9
</pre>
<b>24-Hour Dynamics Analysis</b>
Over the last 24 hours, the download speed averaged <code>140 Mbps</code>, but we saw a massive drop to <code>20 Mbps</code> at 8:00 PM right as device count jumped from <code>4</code> to <code>11 devices</code>. Clearly, someone's hogging the bandwidth or the ISP's mice were busy chewing on the fiber line again. Latency remained stable except for a brief spike during peak hours.
<b>Data Transfer (Latest Test)</b>
<pre>
Downloaded: 160.0 MB
Uploaded: 70.0 MB
</pre>
<b>Conclusion</b>
Expect periodic speed drops whenever local frees stream 4K movies or the ISP potato infrastructure struggles.
netmon/
├── assets/ # Logo & documentation media assets
├── graphs/ # Generated 24h matplotlib graph images
├── main.py # Main execution loop & orchestrator
├── runner.py # Speedtest-cli and nmap scan execution & parsing
├── sqlite.py # SQLite database operations & schema management
├── models.py # Domain data models (NetworkMetric, SpeedTest)
├── graphs.py # Matplotlib graph rendering engine
├── ai.py # OpenAI API client & sarcastic text generator
├── tg.py # Telegram bot dispatch helper
├── config.py # Environment variable validation & config
├── pyproject.toml # Project metadata & dependencies
├── uv.lock # Locked, reproducible dependency versions
└── LICENSE # MIT License file
Distributed under the MIT License. See LICENSE for more details.