WatchYourLAN — Lightweight Self-Hosted Network IP Scanner

Introduction

WatchYourLAN is a lightweight self-hosted network scanner that continuously monitors your local network for connected devices. It uses ARP scanning to detect hosts, maintains a history of device connections, and provides notifications when new or unknown devices appear on your network — all through a clean web dashboard.

What WatchYourLAN Does

• Continuously scans your local network using ARP to discover all connected devices
• Maintains a historical database of every device that has connected to your network
• Sends notifications via Telegram, Gotify, ntfy, or webhooks when new devices appear
• Displays device information including IP, MAC, hostname, and vendor in a web UI
• Exports metrics to InfluxDB or Prometheus for visualization in Grafana

Architecture Overview

WatchYourLAN is a single Go binary that runs periodic ARP scans on configured network interfaces. Discovered devices are stored in a SQLite database with timestamps for historical tracking. The web UI is served from the same binary using embedded templates. Known devices can be marked as trusted, and any new unrecognized MAC address triggers configurable notifications. The application runs with host networking to access the local ARP table directly.

Self-Hosting & Configuration

• Run with Docker using --network=host to enable direct LAN access for ARP scanning
• Set the IFACES environment variable to specify which network interfaces to scan
• Configure notification endpoints via environment variables for Telegram, Gotify, or ntfy
• Data persists in a SQLite file mapped to a Docker volume at /data
• Optionally export to InfluxDB by setting INFLUX_ENABLE=true with connection details

Key Features

• Real-time ARP-based network scanning with configurable intervals
• Historical device tracking with first-seen and last-seen timestamps
• Notifications for new unknown devices via multiple channels
• MAC vendor lookup for device identification
• Grafana-ready metrics export via InfluxDB or Prometheus endpoint

Comparison with Similar Tools

• Pi-hole — DNS-level ad blocking with network view; WatchYourLAN focuses purely on device discovery and tracking
• Nmap — Powerful network scanner requiring CLI expertise; WatchYourLAN offers continuous monitoring with a web UI
• NetAlertX — More feature-rich with port scanning; WatchYourLAN is lighter and simpler to deploy
• Fing — Commercial app; WatchYourLAN is fully self-hosted and open source
• arpwatch — Classic ARP monitor without a UI; WatchYourLAN adds a modern web dashboard and notifications

FAQ

Q: Why does WatchYourLAN need host networking? A: ARP scanning requires direct Layer 2 access to the local network, which is only possible with host networking mode in Docker.

Q: Can it scan multiple network interfaces? A: Yes, set IFACES to a space-separated list of interfaces like IFACES="eth0 wlan0".

Q: How often does it scan the network? A: The default scan interval is 60 seconds, configurable via the TIMEOUT environment variable.

Q: Does it detect devices using static IPs? A: Yes, ARP scanning detects any device responding on the local network segment regardless of how it obtained its IP.

Sources

• https://github.com/aceberg/WatchYourLAN
• https://hub.docker.com/r/aceberg/watchyourlan