WatchYourLAN

Lightweight LAN monitoring, honestly reviewed. Not enterprise SIEM software — just a tool that tells you what’s on your network and when.

TL;DR

• What it is: MIT-licensed network IP scanner with a web GUI, written in Go — tells you what devices are on your network, alerts you when a new one appears, and exports history to Grafana [README][2].
• Who it’s for: Homelabbers, self-hosters, and small-office owners who want passive network visibility without the overhead of enterprise tools. Smart home users who keep adding IoT devices and want to know when something new shows up [3][4].
• Cost savings: Commercial network monitoring tools (Fingbox, Auvik, Domotz) run $60–$300+/year. WatchYourLAN runs free on any Linux machine or a $5/mo VPS — including Raspberry Pi [4].
• Key strength: Minimal setup. One Docker command, provide your network interface and timezone, and it’s scanning. History in a database, Grafana dashboard optional but easy [4][README].
• Key weakness: No built-in authentication. The app is wide open on port 8840 by default, and because it requires host network mode, you can’t just stick a reverse proxy in front of it without firewall rules [README]. Not a tool for multi-user teams or anything with a compliance requirement.

---

What is WatchYourLAN

WatchYourLAN is a Go-based network scanner with a web GUI that runs ARP scans against your local network on a configurable interval (default: every 120 seconds). Its job is narrow: keep a list of every IP/MAC address that appears on your network, notify you when a new one shows up, and track when hosts go online and offline [README].

The project is built by a solo developer (aceberg) and sits at 6,844 GitHub stars with 237 forks [merged profile]. It’s not backed by a company. It’s a one-person open-source tool that’s earned its stars by doing a specific thing well and not trying to be more than it is.

Version 2.0 (released in late 2024) was a breaking change from v1: it added a proper database backend (SQLite by default, PostgreSQL optional), a basic API, InfluxDB2 export for Grafana dashboards, and the ability to pass arguments directly to arp-scan for VLAN support [2]. The internal architecture shifted from flat file storage to a proper DB, which broke backward compatibility but made the tool actually useful for long-term history [2].

The web interface runs on port 8840 and is built with Bootstrap-based themes from Bootswatch — functional, not beautiful, but readable. You get a table of hosts with IP, MAC address, hostname (resolved via DNS), vendor (from MAC prefix lookup), first seen, last seen, and online/offline status [README][4].

---

Why people choose it

The WatchYourLAN pitch is simple: you have a home network with 20–50 devices, IoT gadgets appearing and disappearing, and occasionally something suspicious shows up that you didn’t put there. You want to know. Most tools that solve this are either too heavy (Nmap requires manual runs, full SIEM solutions require a dedicated box and half a day of config), too expensive (Fingbox is $99 hardware), or overkill for the actual use case.

WatchYourLAN threads the needle between “run nmap manually” and “deploy a full network monitoring stack.” It’s passive, continuous, and lightweight enough to live on a Raspberry Pi alongside everything else [4].

The smart home angle is where it gets practically useful. The XDA Developers article on useful homelab Docker containers [3] highlights similar tools in this space for the same reason: smart home setups grow chaotically. New IoT devices appear constantly — from family members, from Amazon shipments, from guests. A scanner that alerts you when an unknown device joins the network turns a reactive problem (something’s not working, why?) into a proactive one (something new appeared, do I recognize it?).

Pi My Life Up’s deployment guide [4] frames WatchYourLAN as a lightweight alternative to PiAlert (now NetAlertX), and that framing is accurate. PiAlert/NetAlertX has more features — device classification, network topology mapping, deeper alerting logic — but also more configuration surface area. WatchYourLAN is the option you reach for when you want the core capability (what’s on my network, what’s new) without the setup overhead.

The r/selfhosted community received the 2.0 release positively [2]. The thread author (the developer) laid out the breaking changes clearly and the reception was warm. Comments focused on practical questions: VLAN support (addressed via arp-scan args), database migration (not automated from v1, manual migration required), and Raspberry Pi compatibility (supported, including armv5/v6/v7/arm64) [2].

---

Features

Core scanning:

• ARP scanning via arp-scan on one or more network interfaces [README]
• Configurable scan interval (default 120 seconds) [README]
• VLAN support via direct arp-scan argument passthrough — see the VLAN_ARP_SCAN.md docs [README][2]
• MAC vendor lookup (tells you the manufacturer from the MAC prefix) [README]
• DNS hostname resolution [2]
• Online/offline status tracking with history [README]

Alerting:

• Notifications via Shoutrrr — which covers Discord, Email, Gotify, Matrix, Ntfy, Pushover, Slack, Telegram, and Generic Webhooks out of the box [README]
• Trigger: new host detected on the network [README]
• No built-in alerting for offline events (you can see history in the UI, but notification triggers are new-host only per the README) [README]

Storage and export:

• SQLite by default, PostgreSQL via connection string [README][2]
• InfluxDB2 export for Grafana dashboards — configurable bucket, org, token, TLS skip [README]
• Prometheus /metrics endpoint (enable via config) [README]
• History retention configurable via TRIM_HIST (removes records older than N hours, default 48) [README]

Configuration:

• Three ways to configure: config file (config_v2.yaml), environment variables, or the web GUI [README]
• Bootswatch themes, light/dark color mode [README]
• Basic API (added in 2.0) [2]

Auth:

• None built in. The README explicitly says to use Authelia or the developer’s own ForAuth app if you need auth [README]
• Hard warning in the README: because WatchYourLAN requires host network mode, its port will be exposed even with a reverse proxy in front. Firewall rules are required to actually restrict access [README]

Deployment formats:

• Docker (single container, host network mode required)
• Binary packages: .deb, .rpm, .apk (Alpine), .tar.gz [README]
• Architectures: amd64, i386, arm_v5, arm_v6, arm_v7, arm64 [README]
• Unofficial YunoHost package [merged profile]

---

Pricing: what you’re actually spending

WatchYourLAN: free. MIT license. No cloud tier, no premium features, no subscription [README].

What you pay instead:

• A machine to run it on — Raspberry Pi you already own, or a $5–6/mo VPS (Hetzner CX11, Oracle Free Tier)
• Electricity, if you care
• Your time to set it up and handle the auth gap (firewall rules or a proxy)

For comparison, what you’d pay for the commercial equivalent:

• Fingbox (hardware network monitor): ~$99 one-time, with a free cloud tier and optional subscription for advanced features
• Domotz: $35/mo per network for professional network monitoring
• Auvik: pricing not public, enterprise-targeted, starts around $150+/mo
• Paessler PRTG: $2,149/year for 500 sensors

None of those are direct competitors for a homelab use case — they’re over-engineered for what WatchYourLAN’s audience needs. The realistic comparison is Fingbox vs. WatchYourLAN. Fingbox is plug-and-play with a polished mobile app; WatchYourLAN requires a Docker-capable machine and 30 minutes of setup. Over three years, WatchYourLAN on a machine you already own is $0 vs. Fingbox at $99 plus potential subscription fees.

If you’re already running a Raspberry Pi or homelab server, the marginal cost of WatchYourLAN is zero.

---

Deployment reality check

The Pi My Life Up guide [4] is the most detailed third-party walkthrough. The short version: it’s genuinely easy if you already have Docker running. The command in the README is three environment variables and a volume mount. Realistic time to first working scan: 5–15 minutes for someone who has Docker set up [4].

The one gotcha that matters: host network mode. Docker containers normally run in an isolated network namespace, which lets WatchYourLAN be proxied cleanly. WatchYourLAN needs --network=host because ARP scanning only works on the physical network interface — you can’t ARP-scan from inside a bridge network. This means:

1. Port 8840 is bound directly to the host, not to Docker’s internal routing
2. A reverse proxy (nginx, Caddy, Traefik) in another container won’t intercept requests to port 8840 on the host interface — you need either a reverse proxy on the same host (not in Docker) or firewall rules to block external access [README]

The README flags this clearly with a warning emoji [README], which is good. It’s not a gotcha they’re hiding. But it does mean the auth story requires deliberate action — the default install is accessible to anyone on your network and potentially beyond.

Practical steps beyond the basic Docker run:

1. Firewall port 8840 to your LAN subnet only (ufw allow from 192.168.1.0/24 to any port 8840)
2. If you want internet access, put it behind a VPN (Tailscale, WireGuard) rather than exposing it publicly
3. For auth: deploy Authelia or ForAuth in front of it — the developer provides a docker-compose-auth.yml example [README]

For VLAN setups: the ARP_ARGS config variable lets you pass arguments directly to arp-scan. The repo has a dedicated docs/VLAN_ARP_SCAN.md doc for this. It works, but requires understanding which interfaces map to which VLANs [README][2].

Database: SQLite works fine for a single-user homelab. If you’re scanning a large network with hundreds of hosts and sub-minute intervals, the PostgreSQL option gives you better write performance and easier backup integration [README].

---

Pros and cons

Pros

• Genuinely lightweight. Written in Go, single binary, small Docker image. Runs comfortably alongside 20 other containers on a Raspberry Pi 4 [4][README].
• MIT license. Use it, embed it, fork it, no questions asked [README].
• Grafana/InfluxDB integration is first-class. Not an afterthought — the InfluxDB2 config matches Grafana’s data source config exactly, and Prometheus metrics are supported [README]. If you already have a Grafana stack, WatchYourLAN drops into it without custom work.
• Multiple notification channels. Shoutrrr covers basically every notification service you might use — Telegram, Discord, Ntfy, Pushover, Slack, email, generic webhooks [README]. You’re not stuck with one.
• Multiple deployment targets. Docker is the obvious path, but native packages for deb/rpm/apk mean you can run it without Docker if your environment doesn’t support containers [README].
• Broad architecture support. armv5 through arm64 and amd64 — it works on old Raspberry Pis, not just modern hardware [README].
• Actively maintained. 286 commits, regular releases, CHANGELOG maintained, developer responds in GitHub Discussions [README website].
• VLAN support. Via arp-scan arguments — not the most elegant UI for it, but it works for advanced setups [README][2].

Cons

• No built-in auth. The biggest real limitation. Host network mode makes this harder than usual to mitigate, and the warning is easy to miss [README]. Non-technical users who deploy this without reading carefully will have an open web interface.
• New-host-only alerting. The notification system fires when a new device appears. Offline alerting (device disappeared) is not a notification trigger — only visible in the UI history [README]. If your use case is “alert me when a device goes down,” this doesn’t cover it.
• Solo developer project. Not backed by a company, no commercial tier, donation-funded. The README explicitly asks for donations [README]. For a homelab tool this is fine; for anything production-critical, factor in the bus risk.
• History trimming is aggressive by default. TRIM_HIST defaults to 48 hours — two days of history before records are pruned [README]. You’ll want to change this to something useful (168 for a week, 720 for 30 days) immediately after install.
• No mobile app. The web UI works in a mobile browser, but there’s no native app and no push notification integration outside of Shoutrrr channels [README].
• Breaking 2.0 migration. If you were on v1, there was no automated migration path — manual process required [2]. For new installs this is irrelevant, but worth knowing if you’re inheriting someone else’s setup.
• API is basic. Added in 2.0, but it’s minimal [2]. Not suitable for integration into a larger network management workflow that needs programmatic control.

---

Who should use this / who shouldn’t

Use WatchYourLAN if:

• You’re running a homelab or home network and want continuous visibility into what devices are connected.
• You keep adding smart home devices and want automatic alerts when something new appears (or something unexpected joins).
• You already have Grafana running and want network host data in your dashboards — the InfluxDB/Prometheus integration makes this easy.
• You want something that runs on a Raspberry Pi without consuming meaningful resources.
• You need notification delivery to Telegram, Discord, Ntfy, or other Shoutrrr-supported channels.

Skip it (use NetAlertX instead) if:

• You want more advanced alerting logic — offline notifications, port change detection, device classification by category.
• You need a polished UI with network topology visualization.
• You’re managing a larger network (20+ device types) and want more structured inventory management.

Skip it (use Fingbox instead) if:

• You want plug-and-play with a mobile app and no Linux command line.
• You’re not running any server or Raspberry Pi and don’t plan to.
• You’re willing to pay ~$99 hardware cost for zero setup friction.

Skip it entirely if:

• Your compliance team is involved. No auth, no audit logs, no RBAC.
• You need alerting when devices go offline, not just when new devices appear.
• You’re managing a multi-site network — this tool is designed for a single LAN segment (or VLAN-segmented network with manual config).

---

Alternatives worth considering

• NetAlertX (formerly PiAlert) — the natural comparison. More features: offline alerts, device classification, network topology, plugin system. More configuration overhead. The XDA article [3] highlights it as the choice for deeper network inventory management. If WatchYourLAN feels too minimal, NetAlertX is the next step up.
• Nmap — the classic. More powerful scanning (port scanning, OS fingerprint), but no persistent UI, no automatic history, no alerting out of the box. WatchYourLAN’s job is to automate the “run nmap manually” workflow with a proper persistent store.
• Angry IP Scanner — cross-platform desktop GUI scanner, well-maintained. No continuous monitoring, no alerting, no history. Point-in-time scans only.
• Fingbox — hardware device ($99) with polished mobile app, cloud integration, and zero Linux required. The non-technical option. No self-hosted infrastructure needed; in exchange, your network data goes to Fing’s cloud.
• Domotz — professional network monitoring aimed at MSPs and IT teams. Per-network subscription pricing, full asset inventory, remote access. Significant overkill and cost for a homelab.
• Zabbix / LibreNMS — full enterprise-grade network monitoring. SNMP, IPMI, agent-based monitoring, alerting pipelines. Useful if you’re running actual infrastructure; wildly overbuilt for tracking IoT devices on a home network.

For a homelab user, the realistic shortlist is WatchYourLAN vs. NetAlertX. WatchYourLAN if you want minimal setup and Grafana integration. NetAlertX if you want more alerting logic and don’t mind the additional configuration.

---

Bottom line

WatchYourLAN does one thing: it watches your LAN. It tells you what’s there, when something new arrives, and how to get that data into Grafana. It doesn’t try to be a security appliance, a SIEM, or an enterprise asset management system. That restraint is its biggest feature — you can have it scanning in 15 minutes and never need to touch it again. The auth gap is real and requires deliberate mitigation (firewall rules, VPN, or a proxy), but the README is honest about it. For anyone running a homelab or smart home with an existing Docker stack, this is the kind of tool that sits quietly in the background and surfaces the information you occasionally need — particularly when something joins your network that shouldn’t be there.

---

Sources

1. daily.dev — aceberg/WatchYourLAN post (35 upvotes, Sep 2024). https://app.daily.dev/posts/aceberg-watchyourlan-lightweight-network-ip-scanner-can-be-used-to-notify-about-new-hosts-and-moni-vwayknz4l
2. r/selfhosted — WatchYourLAN 2.0 Release (posted by aceberg_). https://www.reddit.com/r/selfhosted/comments/1f5j8ij/watchyourlan_20_release/
3. Samir Makwana, XDA Developers — “These 5 obscure Docker containers help solve my biggest smart home problems” (Nov 5, 2025). https://www.xda-developers.com/obscure-docker-containers-solve-smart-home-problems/
4. Pi My Life Up — “Monitor your LAN using Docker and WatchYourLAN”. https://pimylifeup.com/docker-watchyourlan/
5. mstarzecnews — digest post mentioning WatchYourLAN (Sep 20, 2024). https://mstarzecnews.prose.sh/2024-09-20

Primary sources:

• GitHub repository and README: https://github.com/aceberg/WatchYourLAN (6,844 stars, MIT license)
• Docker Hub image: https://hub.docker.com/r/aceberg/watchyourlan
• Shoutrrr notification docs: https://nicholas-fedor.github.io/shoutrrr/