adguard-monitor/README.md

AdGuard Monitor

Monitoring service for AdGuard DNS queries with notifications sent to Home Assistant.

Who is this for?

This is for me mainly, so let's see if you need it too. Adguard Monitor is designed for openclaw, which should usually NEVER make a request that needs to be blocked. If it does, I want to know about it immediately.

Features

• Multi-Client Support: Monitor specific IP addresses and receive nicknamed notifications (e.g., "BLOCKED: My Laptop").
• Strict Configuration: Fails fast if environment variables are missing.
• Home Assistant Notifications: Native mobile push messages for blocked queries.
• Structured Logging: UTF-8 encoded logging for unicode emoji support.

Setup

1. Clone the repository.
2. Install dependencies:

   pip install -r requirements.txt
   

3. Configure environment: Copy .env.example to .env and fill in your details:

   cp .env.example .env
   

4. Run the monitor:

   python monitor.py --interval 15
   

Environment Variables

• ADGUARD_URL: Full URL of your AdGuard instance (e.g., http://192.168.1.50).
• ADGUARD_USER/PASSWORD: API credentials.
• CLIENTS: A JSON-formatted dictionary mapping IPs to display names.
• HASS_URL/TOKEN: Home Assistant mobile notification endpoint and Long-Lived Access Token.