Show HN: Netmon – self-hosted LAN monitor with sarcastic AI reports to Telegram

Notifications You must be signed in to change notification settings

Fork 0

Star 1

BranchesTags

Open more actions menu

Folders and files

NameName

Last commit message

Last commit date

Latest commit

History

3 Commits

3 Commits

assets

assets

graphs

graphs

.env.example

.env.example

.gitignore

.gitignore

.python-version

.python-version

LICENSE

LICENSE

README.md

README.md

ai.py

ai.py

config.py

config.py

graphs.py

graphs.py

main.py

main.py

models.py

models.py

pyproject.toml

pyproject.toml

pyrightconfig.json

pyrightconfig.json

runner.py

runner.py

sqlite.py

sqlite.py

tg.py

tg.py

uv.lock

uv.lock

Repository files navigation

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.

Features & Workflow

Every hour (SLEEP_TIME in main.py, default 3600 seconds):

Speed Test: Measures download/upload speeds, ping latency, ISP, and test server details using speedtest-cli.

LAN Scan: Scans the local subnet using nmap ARP scan to count active connected devices.

Local Storage: Saves metrics & device tallies directly to a local metrics.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 a 24-hour trend graph via matplotlib alongside a sarcastic LLM analysis of network load and speed fluctuations.

Tech Stack

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

Requirements

OS: macOS or Linux (nmap --iflist required; Windows not supported out of the box).

uv — manages the Python version, virtualenv, and locked dependencies for you. No manual python3/venv/pip juggling.

System Binaries: nmap and speedtest-cli installed system-wide.

Passwordless sudo for nmap — device counting needs a real ARP scan (raw sockets), which requires root; see one-time setup below.

Tokens: Telegram Bot Token, Telegram Chat ID, and an API key for your OpenAI-compatible provider (not needed if you point AI_BASE_URL at a local LLM server).

Quick Start

1. System Dependencies

macOS (Homebrew):

brew install nmap speedtest-cli

Linux (Debian/Ubuntu):

sudo apt update && sudo apt install -y nmap speedtest-cli

1. Allow Passwordless nmap (one-time)

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.

1. Clone & Setup Environment

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.

1. Configure .env

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.

1. Run the Bot

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.

Example Output

Hourly Short Status Update

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

4-Hour Detailed Report (With Graph & AI Analysis)

Every 4 hours, the bot sends a 24-hour matplotlib graph accompanied by a sarcastic LLM-generated report:

Network Speed Test Report (24h Analysis)

Client: MyISP Server: New York

Latest Test Metrics

Download: 178.5 Mbps Upload: 45.2 Mbps Ping: 23.1 ms Devices Online: 9

24-Hour Dynamics Analysis Over the last 24 hours, the download speed averaged 140 Mbps, but we saw a massive drop to 20 Mbps at 8:00 PM right as device count jumped from 4 to 11 devices. 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.

Data Transfer (Latest Test)

Downloaded: 160.0 MB Uploaded: 70.0 MB

Conclusion Expect periodic speed drops whenever local freeloaders stream 4K movies or the ISP potato infrastructure struggles.

Project Structure

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

License

Distributed under the MIT License. See LICENSE for more details.

About

Self-hosted network monitor — hourly speed tests, LAN device counts via ARP scan, and sarcastic AI-generated reports delivered to Telegram.

Topics

python

speedtest

self-hosted

nmap

network-monitoring

telegrambot

uv

Resources

Readme

License

MIT license

Uh oh!

There was an error while loading. Please reload this page.

Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks

Report repository

Releases

No releases published

Packages 0

Uh oh!

There was an error while loading. Please reload this page.

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

Python 100.0%