What is NetAlertX? Features, Setup, and Network Monitoring Guide
NetAlertX is a free, open-source tool that scans your LAN, keeps an inventory of every connected device and alerts you when something new or unexpected appears. This guide explains what it does and how to run it with Docker.
See Every Device on Your Network, and Know When It Changes
Most networks grow without a clear inventory. NetAlertX gives homelabs, IT teams and service providers a live list of connected devices, with alerts for new connections, disconnections and IP changes.
Device Discovery
Finds new and unknown devices and tracks when they connect or leave.
Instant Alerts
Sends notifications through Telegram, ntfy, Pushover and many more.
Local by Default
Data stays on your own server unless you set up cloud notifications.
What Is NetAlertX?
NetAlertX is an open-source network visibility and asset-discovery framework. It scans your local network, records the devices it finds, and tells you when something changes. The project describes itself as a “network source of truth” (NSoT): one place where you can see which devices exist, where they are and when they were last online.
It grew out of the Pi.Alert project, which its README credits to original creator pucherot, and today it is developed under the netalertx organization on GitHub under the GPL-3.0 license. It runs as a Docker container with a web interface, and it can also be installed on bare metal, on Home Assistant or on Unraid.
By its own description it sits between a simple network scanner and a full monitoring or SIEM platform: it focuses on discovery and noise-free alerting, without the overhead of a large enterprise tool.
Why Monitor Your Network?
You cannot protect devices you do not know about. A new device appearing on your LAN could be a harmless guest phone, a forgotten smart plug or an unauthorized machine. Regular discovery helps you notice:
- Unknown or unauthorized devices on the network
- Devices that go offline when they should always be on, such as servers, cameras and NAS boxes
- IP address changes and conflicts in your addressing plan
- Changes to your public internet IP address
For a home lab this is peace of mind. For IT teams and managed service providers it is a simple way to catch shadow IT and keep an up-to-date device inventory.
Key Features
Continuous device discovery
Detects new devices, re-connections, disconnections, “always connected” devices that go down, device IP changes and internet IP changes.
Presence detection
Track whether important devices are online, such as phones, servers or IoT equipment.
Notifications
Send alerts to more than 80 services through Apprise, including Telegram, or use native Pushsafer, Pushover and ntfy publishers.
Plugins
Extend discovery and notifications with the plugin system, and build your own scanner with an auto-generated interface.
Workflows
Automate housekeeping, such as assigning new devices to a network node, grouping devices by vendor or cleaning up old entries.
Multi-site monitoring
Sync Nodes let remote sites, VLANs and branch offices report back to a central hub for one combined view.
Integrations
Connect to Home Assistant, use the API, send webhooks to automation tools or export Prometheus metrics.
Local-first privacy
Scan data is stored locally. Nothing leaves your network unless you configure notifications or integrations.
Supported Discovery Methods
NetAlertX can find devices in several ways, depending on your network. The project lists these built-in methods:
| Method | How it finds devices |
|---|---|
| arp-scan | Scans the local network segment directly |
| Pi-hole database import | Reads devices from a Pi-hole database |
| Pi-hole DHCP leases import | Reads current leases from Pi-hole |
| Generic DHCP leases import | Reads leases from another DHCP server |
| UniFi controller import | Pulls the client list from a UniFi controller |
| SNMP router import | Reads devices from an SNMP-enabled router |
More scanners are available as plugins. See the plugins overview for the full list.
How to Set Up NetAlertX with Docker
Docker is the recommended way to run NetAlertX. The commands below follow the quick start in the official repository. Check the Docker installation guide for any changes, especially when you upgrade an older installation.
Install Docker
Use a Linux host (a small server, mini PC or Raspberry Pi works) with Docker installed. NetAlertX should run on the network you want to scan.
Create a data folder
Choose a folder for persistent data. The official note says it should contain a config and a db folder.
mkdir -p /opt/netalertx/config /opt/netalertx/dbIf the container reports permission errors, check the ownership requirements in the Docker guide for your version.
Start the container
Run the official image. Replace the data path with your own folder:
docker run -d \
--network=host \
--restart unless-stopped \
--cap-add=NET_RAW \
--cap-add=NET_ADMIN \
--cap-add=NET_BIND_SERVICE \
-v /opt/netalertx:/data \
-v /etc/localtime:/etc/localtime:ro \
--tmpfs /tmp:uid=20211,gid=20211,mode=1700 \
-e PORT=20211 \
-e APP_CONF_OVERRIDE='{"GRAPHQL_PORT":"20214"}' \
ghcr.io/netalertx/netalertx:latest--network=host lets NetAlertX see your LAN, and the network capabilities allow low-level scanning such as ARP.
Open the web interface
Browse to the server’s address on the port you set:
http://SERVER-IP:20211Supported browsers are Chrome and Firefox. The first scans can take a few minutes to fill the device list.
Configure scanning and notifications
In Settings, enable the discovery method that matches your network, set how often it runs, and add a notification service so you receive alerts for new devices.
Review and label your devices
Give each device a name and type, mark known devices and use the network view to organize them. Once your inventory is clean, new or unexpected devices stand out immediately.
Prefer another method? The project also documents bare-metal installation, a Home Assistant add-on and an Unraid app.
Security Best Practices
NetAlertX stores information about every device on your network, so protect the dashboard like any admin tool:
- Do not expose the web interface directly to the internet
- Place it behind a reverse proxy that requires authentication
- Use a firewall to limit who can reach the interface
- Keep the container updated to receive security fixes
- Back up the
configanddbfolders regularly
Troubleshooting
Devices on other subnets are missing
ARP scans only see the local segment. Use the project’s remote-network options or Sync Nodes for other VLANs and sites.
Scan finds nothing
Make sure the container has network access, such as --network host on Linux, and that the scan method is enabled in Settings.
Permission errors
Low-level scanning needs capabilities such as NET_RAW. Confirm the capabilities in your run command.
Too many notifications
On large networks, use notification throttling so new-device alerts stay useful.
Wi-Fi-only networks may need an alternate scanner for accurate detection. Check the GitHub issues and the official documentation for the latest fixes.
NetAlertX vs Other Tools
The NetAlertX README lists several alternatives. This table summarizes them as the project describes them:
| Tool | Focus |
|---|---|
| NetAlertX | Discovery-focused asset visibility and alerting (open source, self-hosted) |
| Fing | Network scanner app for internet security (commercial, phone app, proprietary hardware) |
| NetBox | Network source of truth and IPAM |
| Zabbix / Nagios | Infrastructure monitoring |
| Domotz | Commercial monitoring and remote management for MSPs and multi-site teams |
These descriptions come from the NetAlertX project, not from independent testing. Choose the tool that fits your size, budget and how deep your monitoring needs to be.
Frequently Asked Questions
What is NetAlertX used for?
It discovers devices on your network, keeps an inventory and alerts you to new devices, disconnections and IP changes.
Is NetAlertX free?
Yes. It is open source under the GPL-3.0 license.
Does NetAlertX send my data to the internet?
Not by default. Data stays local unless you configure cloud notifications or integrations.
Can I run it without Docker?
Yes. The project provides a bare-metal installation guide, a Home Assistant add-on and an Unraid app.
Can it monitor multiple sites or VLANs?
Yes. Sync Nodes let remote networks send their device data to a central hub.
Where is the data stored?
In the config and db folders of the data directory. Back them up regularly.
Conclusion
NetAlertX is a practical way to gain visibility of your network without deploying a heavy monitoring platform. It finds devices, tracks changes and alerts you quickly, and it runs easily in Docker. If you manage a home lab, a small office or several customer sites, it is worth testing as your device inventory and early-warning tool.
More Networking and Infrastructure Guides
Explore practical networking, Linux, Windows Server, Azure and virtualization tutorials on VMoreCloud.
Sources & Further Reading
- NetAlertX on GitHub (README, features and quick start)
- NetAlertX official documentation
- NetAlertX website
Technical note: commands and options can change between NetAlertX releases. Confirm them in the official documentation and test on a non-critical host before you rely on the tool. Only scan networks that you own or are authorized to monitor.