NetAlertX - Network, presence scanner and alert framework

Get visibility of what’s going on on your WIFI/LAN network and enable presence detection of important devices. Schedule scans for devices, port changes and get alerts if unknown devices or changes are found. Write your own Plugin with auto-generated UI and in-build notification system. Build out and easily maintain your network source of truth (NSoT).

📋 Table of Contents

• Features
• Documentation
• Quick Start
• Alternative Apps
• Security & Privacy
• FAQ
• Known Issues
• Donations
• Contributors
• Translations
• License

🚀 Quick Start

Start NetAlertX in seconds with Docker:

docker run -d --rm --network=host \
  -v local_path/config:/app/config \
  -v local_path/db:/app/db \
  --mount type=tmpfs,target=/app/api \
  -e PUID=200 -e PGID=300 \
  -e TZ=Europe/Berlin \
  -e PORT=20211 \
  ghcr.io/jokob-sk/netalertx:latest

Need help configuring it? Check the usage guide or full documentation.

For Home Assistant users: Click here to add NetAlertX

For other install methods, check the installation docs

📑 Docker guide	🚀 Releases	📚 Docs	🔌 Plugins	🤖 Ask AI

📷 Click for more screenshots

Head to https://netalertx.com/ for even more gifs and screenshots 📷.

📦 Features

Scanners

The app scans your network for New devices, New connections (re-connections), Disconnections, “Always Connected” devices down, Devices IP changes and Internet IP address changes. Discovery & scan methods include: arp-scan, Pi-hole - DB import, Pi-hole - DHCP leases import, Generic DHCP leases import, UNIFI controller import, SNMP-enabled router import. Check the Plugins docs for a full list of avaliable plugins.

Notification gateways

Send notifications to more than 80+ services, including Telegram via Apprise, or use native Pushsafer, Pushover, or NTFY publishers.

Integrations and Plugins

Feed your data and device changes into Home Assistant, read API endpoints, or use Webhooks to setup custom automation flows. You can also
build your own scanners with the Plugin system in as little as 15 minutes.

Workflows

The workflows module allows to automate repetitive tasks, making network management more efficient. Whether you need to assign newly discovered devices to a specific Network Node, auto-group devices from a given vendor, unarchive a device if detected online, or automatically delete devices, this module provides the flexibility to tailor the automations to your needs.

📚 Documentation

Supported browsers: Chrome, Firefox

• [Installation] Docker
• [Installation] Home Assistant
• [Installation] Bare metal
• [Installation] Unraid App
• [Setup] Usage and Configuration
• [Development] API docs
• [Development] Custom Plugins

…or explore all the documentation here.

🔐 Security & Privacy

NetAlertX scans your local network and can store metadata about connected devices. By default, all data is stored locally. No information is sent to external services unless you explicitly configure notifications or integrations.

To further secure your installation:

• Run it behind a reverse proxy with authentication
• Use firewalls to restrict access to the web UI
• Regularly update to the latest version for security patches

See Security Best Practices for more details.

❓ FAQ

Q: Why don’t I see any devices?
A: Ensure the container has proper network access (e.g., use --network host on Linux). Also check that your scan method is properly configured in the UI.

Q: Does this work on Wi-Fi-only devices like Raspberry Pi?
A: Yes, but some scanners (e.g. ARP) work best on Ethernet. For Wi-Fi, try SNMP, DHCP, or Pi-hole import.

Q: Will this send any data to the internet?
A: No. All scans and data remain local, unless you set up cloud-based notifications.

Q: Can I use this without Docker?
A: Yes! You can install it bare-metal. See the bare metal installation guide.

Q: Where is the data stored?
A: In the /config and /db folders, mapped in Docker. Back up these folders regularly.

🐞 Known Issues

• Some scanners (e.g. ARP) may not detect devices on different subnets. See the Remote networks guide for workarounds.
• Wi-Fi-only networks may require alternate scanners for accurate detection.
• Notification throttling may be needed for large networks to prevent spam.
• On some systems, elevated permissions (like CAP_NET_RAW) may be needed for low-level scanning.

Check the GitHub Issues for the latest bug reports and solutions and consult the official documentation.

📃 Everything else

📧 Get notified what’s new

Get notified about a new release, what new functionality you can use and about breaking changes.

🔀 Other Alternative Apps

• PiAlert by leiweibau (maintained, bare-metal install)
• WatchYourLAN - Lightweight network IP scanner with web GUI (Open source)
• Fing - Network scanner app for your Internet security (Commercial, Phone App, Proprietary hardware)
• NetBox - Network management software (Commercial)

💙 Donations

Thank you to everyone who appreciates this tool and donates.

Click for more ways to donate

---

• Bitcoin: 1N8tupjeCK12qRVU2XrV17WvKK7LCawyZM
• Ethereum: 0x6e2749Cb42F4411bc98501406BdcD82244e3f9C7

📧 Email me at [email protected] if you want to get in touch or if I should add other sponsorship platforms.

🏗 Contributors

This project would be nothing without the amazing work of the community, with special thanks to:

pucherot/Pi.Alert (the original creator of PiAlert), leiweibau: Dark mode (and much more), Macleykun (Help with Dockerfile clean-up), vladaurosh for Alpine re-base help, Final-Hawk (Help with NTFY, styling and other fixes), TeroRERO (Spanish translations), Data-Monkey, (Split-up of the python.py file and more), cvc90 (Spanish translation and various UI work) to name a few. Check out all the amazing contributors.

🌍 Translations

Proudly using Weblate. Help out and suggest languages in the online portal of Weblate.

License

GPL 3.0 | Read more here | Source of the animated GIF (Loading Animation) | Source of the selfhosted Fonts