NetAlertX Self-Hosted Network Monitoring for Home Labs
Knowing what is on your network is a huge part of network security. We can document devices and other aspects of the network. However, what if a device appears on the network unannounced or not really in an expected way. Do you have visibility on this? I have been a huge advocate for ARP alert over the years. However, still I am always on the lookout for solutions that provide an interesting spin on these existing types of tools. I would like to introduce you to NetAlertX. It is a clean self-hosted solution that can help you have visibility of devices on your network and at the same time, see which devices are on which IP addresses if you don’t already have a good way to do that.
It runs extremely well in a Docker container and it integrates with solutions like Home Assistant, and also supports advanced notifications using tools like Apprise. Let’s walk through what it does, how to deploy it, and why it’s worth adding to your home or small office setup.
What Is NetAlertX?
First of all, what is NetAlertX? Well, it is a free and open-source self-hosted web app that scans your network continuously to build a live inventory of connected devices. It can send notifications when new devices appear on the network. You will see information like IP addresses and MAC addresses and get alerts when these mappings change or go offline.
Interestingly, it looks very much like another solution that I wrote about some time ago called Pi.Alert. I am thinking it could possibly be a fork of this project since the similarities are uncanny.
What I really like about the solution is it can be deployed in Docker, it is very easy to deploy and it will scale with multiple VLANs and subnet monitoring. The project is currently under active development and provides additional plugins to customize the solution even further.
Key Features of NetAlertX
Here is a rundown of the key features of NetAlertX in your home lab network or elsewhere:
- Scanning in real-time using ARP, DHCP, ping/ICMP, and Nmap
- Change detection for IPs, MAC addresses, hostnames, and open ports
- Notification support for 80+ services via Apprise (email, Telegram, Pushover, etc.)
- Network topology with a built-in SVG dashboard
- Plugin support for DHCP imports, Pi-hole, UniFi, ICMP, and others
- Multi-instance sync across different VLANs or subnets
- MQTT and Home Assistant integration for automations
One of the key features I think is the ability to spot rogue devices. If something comes onto your network, NetAlertX will find it. Also, just from a practical standpoint, these types of solutions like NetAlertX, Arpwatch and others allow you to quickly see the devices YOU place on the network and this is super handy if you need to know quickly what IP address it has grabbed.
How to spin up NetAlertX Using Docker
The recommended way to run NetAlertX is with Docker. Here’s a simple setup to get started:
Create Your docker-compose.yml or Docker Run Command
Below is the docker-compose.yml file for spinning up you NetAlertX container. Replace with your own volume mount locations, container name, etc. Save this file as docker-compose.yml.
version: "3.8"
services:
netalertx:
image: ghcr.io/jokob-sk/netalertx:latest
container_name: netalertx
network_mode: host
restart: unless-stopped
volumes:
- ~/homelabservices/netalertx/config:/app/config
- ~/homelabservices/netalertx/db:/app/db
tmpfs:
- /app/api
environment:
- PUID=200
- PGID=300
- TZ=America/Chicago
- PORT=20211
Note:
network_mode: hostis needed for network scanning since you want to discover things that are likely on the host network.
If you prefer a simple Docker run command you can do the same thing with this command:
docker run -d --rm \
--name netalertx \
--network=host \
-v ~/homelabservices/netalertx/config:/app/config \
-v ~/homelabservices/netalertx/db:/app/db \
--mount type=tmpfs,target=/app/api \
-e PUID=200 \
-e PGID=300 \
-e TZ=America/Chicago \
-e PORT=20211 \
ghcr.io/jokob-sk/netalertx:latestStart the Container
If you are using docker run, you just simply run the command. However, for Docker-Compose, you use the following:
docker compose up -dOnce up and running, NetAlertX will begin scanning your network and building an inventory of connected devices.
Configure Subnets and Interfaces
You can edit the app.conf file directly to add the scan subnets.
Edit the configuration file to include your correct scan subnet(s), like:
#One subnets
SCAN_SUBNETS = ['192.168.1.0/24 --interface=eth0']
##Two subnetsSCAN_SUBNETS = ['192.168.1.0/24 --interface=eth0','192.168.1.0/24 --interface=eth1 --vlan=107']Use ip a or ifconfig to confirm the interface name. Also, most will likely just use the UI to configure the scanned subnets:
Built-In Dashboard for Visual Network Monitoring
NetAlertX includes a visual dashboard that maps out your network devices. You can customize each device with icons, assign trust levels (known, new, blocked), and even tag them for quick filtering.
If you run multiple VLANs or have segmented networks, NetAlertX can combine data into a unified view when set up on multiple hosts with sync enabled.
One of the very cool things that NetAlertX does is provide great network visualizations for your environment. You can Assign devices to particular networks scanned and then it will automatically create a visualization of devices.
Notification Options
NetAlertX supports over 80 notification services through Apprise, including:
- Telegram
- Slack
- Pushover
- Gotify
- Discord
- Email (SMTP)
- Webhooks
- NTFY and MQTT
This allows you to build real-time workflows. For example, when a new device joins your network, you could:
- Send a Telegram alert to your phone
- Trigger an automation in Home Assistant
- Log the event in a local database
Plugins
Out of the box, NetAlertX includes many different plugins to extend its functionality:
- DHCP Server Integration – Import leases from Pi-hole, UniFi, or Freebox
- Advanced Scanning – Use arp-scan,
nmap, or ip neighbor for more detail - Reverse DNS and WHOIS Lookups
- Port Scanning and Monitoring
Each plugin can be toggled on or off, letting you fine-tune the scanning and data you receive.
Home Assistant Integration
If you’re using Home Assistant in your smart home, NetAlertX integrates beautifully via MQTT. You can:
- Create sensors for device status (online/offline)
- Automate based on device presence
- Display device info on dashboards
Imagine lights turning on when your phone connects to Wi-Fi—or receiving an alert when a new MAC address appears on your guest network.
Troubleshooting
Here are a few things to watch out for:
1. Not Using Host Networking
NetAlertX needs to run the container in host mode for the network. If you use bridge mode, it won’t work properly.
2. Incorrect Subnet or Interface
Be sure your subnet matches your LAN (192.168.1.0/24) and that your interface is correct (check with ip a).
3. Missing Plugins
If you want email or Telegram alerts, enable those plugins in the config. Don’t assume a plugin is active by default.
Use Cases for NetAlertX
Here’s how different users are leveraging NetAlertX:
- Home Lab Enthusiasts: Know when new VMs or containers appear or go offline.
- Smart Home Users: Automate lights, alarms, or scenes when devices connect/disconnect
- Small Office Networks: Track BYOD devices and alert when new or unknown ones connect
- Security: Detect intrusions, IP spoofing, or port scanning attempts
I really like that it provides a wide range of functionality for both beginners and advanced users who need a wide range of features and functionality for their networks.
Active Development and Roadmap
NetAlertX is in active development with regular updates. Recent additions to functionality include:
- Improved SVG network visualization
- More plugin integrations (like Freebox)
- In-memory file handling for performance
- Multi-language support and UI themes
You can follow development on GitHub: https://github.com/jokob-sk/NetAlertX
Wrapping up
Should you check out NetAlertX? Absolutely. It is a great platform from what I can tell with just tinkering around with the project. It provides great visibility for your network. It also has really solid notification options and makes use of modern notifications like Apprise. The Integrations are an added bonus here as well, with integrations with Home Assistant, Pi-Hole and others. I think NetAlertX should be on your short list of things to self-host and spin up in the home lab.
