Pi.Alert: arp-scan Device Discovery with Router and Pi-hole Imports
Scan the devices connected to your WIFI / LAN and alert you the connection of unknown devices. It also warns if a "always connected" device disconnects. In addition, it is possible to check web services for availability. For this purpose HTTP status codes and the response time of the service are evaluated.
At a glance
- What is it?
- Pi.Alert is a PHP network monitor that scans your LAN on a cron schedule and alerts you when an unknown device appears or a known one drops off. It is built for Debian-based hosts, most often a Raspberry Pi, and it is the maintained successor to the original pucherot/Pi.Alert.
- Who is it for?
- Adopt Pi.Alert if you already run a Debian-based host on the network you want watched and you want device discovery plus router, Pi-hole or AdGuard imports without a container runtime. Do not adopt it if you need Docker as the deployment model, since that is NetAlertX's territory, or if you cannot run the backend on a cron schedule.
- Can I use it commercially?
- Yes, with conditions. GPL-3.0 is a copyleft licence: if you distribute software that includes it, you must release that software's source code under the same licence. Running it internally without distributing it does not trigger that obligation.
- Is it still maintained?
- Yes. The repository last received commits 1 day ago.
- What is it written in?
- Mainly PHP, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The problem Pi.Alert addresses on a home or small-office LAN
Consumer routers tell you very little about what is attached to them. A device list in a router admin page is a snapshot, it usually has no history, and it rarely tells you when something new appeared at 03:00. Pi.Alert is aimed at the person who wants that history and wants to be told about changes rather than going looking for them. The README describes the core loop plainly: it discovers devices connected to your Wi-Fi or LAN, notifies you when an unknown device appears or a known device goes offline, and additionally warns if a device you have marked as always connected disconnects. That second case matters more than the first in practice. A laptop that joins the network is noise. A camera or a server that stops answering is a signal. Pi.Alert treats both as events and routes them through the same notification path. The target user is someone running a Raspberry Pi or a small Debian box at home, possibly alongside Pi-hole, who wants one web interface for device inventory, owners, locations and groups rather than a spreadsheet.
Scanning plus imports: where Pi.Alert gets its device data
Pi.Alert does not rely on a single discovery method. The README lists arp-scan for local network discovery, and then a set of imports from other systems: Pi-hole 5 and 6 for DNS and DHCP data, FRITZ!Box for active hosts, MikroTik for DHCP leases, UniFi for client devices, OpenWrt and AsusWRT for active hosts, pfSense and OPNsense for active hosts plus DHCP leases and ARP tables, and AdGuard Home for DHCP leases and hosts seen through recent DNS queries. That breadth is the project's main architectural idea. arp-scan only sees what is reachable and responding on the local segment. A DHCP lease table from the router sees devices that are currently asleep. A Pi-hole DNS log sees devices that resolved a name in the last few minutes even if they never answered an ARP request during the scan window. Combining them produces a device list that is more complete than any one source, at the cost of having to configure each source separately. For segments the main instance cannot reach, the companion Pi.Alert-Satellite project scans independently and sends results back to an existing Pi.Alert instance, using the same set of collectors. There is also ICMP monitoring for devices outside the local subnet, which is a different mechanism from ARP discovery: it is a reachability check against a host you have configured, not a discovery sweep.
The backend runs from cron, not as a daemon
The README states that the backend is normally started by the operating system's cron service every five minutes. That single sentence defines most of the system's operational character. There is no long-running process to supervise, no socket to keep open, no service unit to restart after an upgrade. Each run performs the configured scans and imports, stores the results, and sends notifications when relevant changes are detected. It also monitors manually configured hosts and web services in the same pass. The five-minute cadence is the resolution of everything Pi.Alert knows. A device that joins and leaves inside a five-minute window may never be recorded, and an alert about an unknown device arrives up to five minutes after the fact. For a home network that is usually acceptable. For anyone expecting near-real-time intrusion detection, the cron model is the wrong shape and no amount of configuration changes that. The upside is that the failure mode is easy to reason about: if the backend stops, nothing is scanned, and the absence of alerts is silent. Nothing in the README describes a watchdog for the cron job itself, so a broken cron entry looks identical to a quiet network.
Getting it installed on a Debian-based host
The installer is a single root command, quoted from the README:
sudo bash -c "$(wget -qLO - https://github.com/leiweibau/Pi.Alert/raw/main/install/pialert_install.sh)"
Pi.Alert was originally designed for the Raspberry Pi and targets Debian-based systems using apt. The README explicitly directs you to the distribution notes before installing on DietPi, Ubuntu Server or another Debian-based distribution, which is a fair warning that apt assumptions do not always hold. After installation you are pointed at the first-start guide. Login protection is enabled during installation with a randomly generated password, and the README says it can be changed later with pialert-cli, which is documented in docs/PIALERTCLI.md. Backend settings live in pialert.conf, documented in docs/PIALERT_CONF.md. Updating is a second root command:
sudo bash -c "$(wget -qLO - https://github.com/leiweibau/Pi.Alert/raw/main/install/pialert_update.sh)"
The sidebar's Update Check entry shows available releases and their changes, plus the status of the GeoLite2 database. If your installation still uses the older home-directory layout, the README points to a migration guide, docs/MIGRATION_HOME_TO_OPT.md, which implies the current layout places files under /opt. For Proxmox users there is an LXC route through the Proxmox VE Helper-Scripts, which the README notes uses the version from this repository after the container is created and ships its own update command.
Notifications, web service checks and the pieces that fail quietly
Alerts can go to the frontend, email, Pushsafer, Pushover, ntfy or Telegram through the Telegram Bot API. Shoutrrr is described as remaining available as an optional discovery helper, which is a narrower role than a general notification transport. Each channel has its own setup document, and the email and Telegram guides are linked separately in the README, which suggests the configuration is not trivial enough to be self-explanatory. Beyond devices, Pi.Alert monitors internal and external web services by checking HTTP status, response time and SSL certificate information, and alerts when a service becomes unavailable or its status or certificate changes. The certificate part is the useful one: expiry and subject changes are exactly the kind of thing that goes unnoticed until a browser refuses to load a page. Two other features sit outside the monitoring loop. It can detect unwanted or foreign DHCP servers, which is a rogue-DHCP check rather than a device check. And it can run manual Nmap scans and send Wake-on-LAN commands from the interface. Manual is the operative word for Nmap: this is an on-demand action, not a scheduled scan type in the list of collectors. The web interface also covers device metadata (owners, locations, groups, notes), network relationship mapping through routers and switches, events, reports, journals and scan results, and an API used by integrations such as Home Assistant and Homepage.
Where Pi.Alert is the wrong tool
The cron interval is the first hard limit. Anything that needs sub-five-minute detection is outside the design. The second is the dependency on the host. Pi.Alert is a PHP application installed onto a Debian system with apt, and the README's own distribution notes acknowledge that non-Raspberry Pi Debian variants need checking first. If your infrastructure is container-first, this is friction you will feel at every upgrade, because the update path is a shell script run as root rather than an image pull. The third limit is that discovery quality is bounded by the collectors you configure. Install Pi.Alert with only arp-scan on a network with client isolation or a flat VLAN that ARP does not traverse, and the device list will be thin. The README does not claim otherwise, but it is easy to install the project, see a partial list, and conclude the tool is broken when the real issue is that no DHCP or DNS source was wired in. There is also a maintenance question the README answers only indirectly: the GeoLite2 database has a status indicator in the update check, which means it is a component that can go stale independently of the application code. Finally, the project is GPL-3.0. If you intend to redistribute a modified Pi.Alert, or ship it inside a product, the copyleft terms apply to the whole derived work. That is a licensing consideration, not legal advice, and it is worth reading LICENSE.txt rather than assuming permissive terms.
Pi.Alert against NetAlertX and the original project
The README names two related projects directly. pucherot/Pi.Alert is described as the original, currently unmaintained project. NetAlertX began as a Pi.Alert fork and is now an independent, Docker-based project. That is the real fork in the road, and it is about deployment model more than features. Pi.Alert here is installed by a shell script onto a Debian host and updated by a shell script; NetAlertX is delivered as a container. If you already run Docker and want the scanner to be one more compose service with a pinned image tag, NetAlertX fits that workflow and Pi.Alert does not. If you have a Raspberry Pi doing Pi-hole duty and you would rather not add a container runtime to it, Pi.Alert's apt-based install is the shorter path. The README also links a version comparison document, docs/VERSIONCOMPARE.md, for anyone weighing this repository against the original. Read that document rather than assuming the maintained fork is a strict superset, because the fork history means the two projects have diverged in both directions. The Satellite companion is a third option worth noting: if the problem is a second network segment rather than a second scanner design, Pi.Alert-Satellite extends this project instead of replacing it.
Editorial conclusion
Adopt Pi.Alert if you already run a Debian-based host on the network you want watched and you want device discovery plus router, Pi-hole or AdGuard imports without a container runtime. Do not adopt it if you need Docker as the deployment model, since that is NetAlertX's territory, or if you cannot run the backend on a cron schedule. Before committing, verify that arp-scan sees your subnet the way you expect, that your router model appears in the supported import list, and that the GeoLite2 database status shown in the sidebar's Update Check entry is current, since that database is what the update check reports on.
Community notes