A step-by-step tutorial series for setting up a home network monitor: every device on your network, the sites each one looks up, data used per device per day, and alerts when a new device joins or something suspicious happens.
The software is in this repository: a Java (Spring Boot) API, a React web UI, and an optional Python traffic agent. These guides cover everything around it: choosing hardware, preparing a Raspberry Pi or PC, placing it in your network, installing, and running it.
#Read in this order
| # | Guide | You will |
|---|---|---|
| 1 | Overview and planning | Understand what is and is not possible, and pick your setup |
| 2 | Set up a Raspberry Pi | Flash, secure and prepare a Pi as the monitor box |
| 3 | Set up a PC or mini PC | Prepare an old PC, mini PC or laptop instead |
| 4 | Placing the monitor in your network | Choose where the box sits; configure your ISP router (see also guide 12) |
| 5 | Install and configure the application | Deploy with Docker, create the root user, run the first scan |
| 6 | Web activity with Pi-hole | See which sites each device looks up |
| 7 | Data usage and intrusion agent | Get MB per device per day and inbound-probe alerts |
| 8 | Alerts and Telegram | Get notified on your phone |
| 9 | Operations and security | Update, back up, secure, recover a lost password |
| 10 | Troubleshooting | Fix common problems |
| 11 | API reference | Build your own client or collector |
| 12 | ISP router guide | Airtel, Tata Play Fiber and JioFiber: what to test, what users report, workarounds. Read alongside guide 4. |
For an AI assistant or a quick checklist, see skills.md in the repository root. The top-level README is the short version.
#Choose your path
| Goal | Read |
|---|---|
| "Show me devices and alert on new ones," about an hour | 1, 2 or 3, 5, 8 |
| Plus sites visited per device | add 6 |
| Plus data used per device and external intrusion detection | add 4 (gateway or mirror setups) and 7 |
| Just trying it on my laptop first | The top-level README, sections 4 and 12 |
#Conventions used in these guides
$at the start of a line is a command to type; do not type the$.192.168.1.xaddresses are examples. Your router may use192.168.0.x,10.0.0.xor another range. Substitute your own.- monitor box means the Raspberry Pi or PC that runs the monitor. ISP router means the router your internet provider installed.
- Replace
nwmonitor(hostname) andpi(username) with the ones you chose.
#Before you start
Only monitor networks you own or administer. Tell the people who use your network that DNS lookups and data usage are recorded. You are responsible for complying with local rules on monitoring other people's activity.