✓ Verified 💻 Development ✓ Enhanced Data

Adguard

Control AdGuard Home DNS filtering via HTTP API.

Rating: 4.7 (24 reviews)
Downloads: 3,099 downloads
Version: 1.0.0

Overview

Control AdGuard Home DNS filtering via HTTP API.

Complete Documentation

View Source →

AdGuard Home Controller

Manage AdGuard Home DNS filtering from the command line via the REST API.

Requirements

AdGuard Home running with web interface
Admin username and password
curl installed (usually default on macOS/Linux)

Quick Start

bash

# Set password once
export ADGUARD_PASSWORD=your_admin_password

# Use commands
./adguard.sh status
./adguard.sh check example.com
./adguard.sh allow broken-site.com
./adguard.sh block malware.ru

Configuration

Set environment variables for your AdGuard instance:

bash

export ADGUARD_URL="http://192.168.1.100:3000"      # Your AdGuard IP and port
export ADGUARD_USERNAME="admin"                     # Usually 'admin' (default)
export ADGUARD_PASSWORD="your_admin_password"       # REQUIRED

Add to ~/.bashrc or ~/.zshrc for persistence.

Config File Alternative

Create ~/.adguard/config.json (optional):

json

{
  "url": "http://192.168.1.100:3000",
  "username": "admin"
}

Then set ADGUARD_PASSWORD separately for security.

Commands

check

Check if a domain is currently blocked or allowed.

bash

./adguard.sh check doubleclick.net
# ✗ doubleclick.net IS BLOCKED
#   Blocked by: Adblock Plus filter

./adguard.sh check example.com
# ✓ example.com is NOT blocked (allowed)

allow | whitelist

Add a domain to the allowlist (whitelist). Creates an exception rule that overrides blocklists.

bash

./adguard.sh allow broken-site.com
# ✓ Added rule: @@||broken-site.com^
#   Domain: broken-site.com
#   Action: allow

block | blacklist

Add a domain to the blocklist. Creates a custom blocking rule.

bash

./adguard.sh block spyware-domain.ru
# ✓ Added rule: ||spyware-domain.ru^
#   Domain: spyware-domain.ru
#   Action: block

status | stats

Display DNS filtering statistics and protection state.

bash

./adguard.sh status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# AdGuard Home Status
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# Protection: ✓ ENABLED
# 
# DNS Queries: 1,234
# Blocked by rules: 156
# Blocked by safe browsing: 23
# Safe search replacements: 5
# Block rate: 14%
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

toggle | protection

Enable or disable DNS protection. Useful for temporarily disabling filtering.

bash

./adguard.sh toggle
# Disabling protection...
# ✓ Protection is now false

cache-clear

Clear the DNS cache to apply rule changes immediately.

bash

./adguard.sh cache-clear
# Clearing DNS cache...
# ✓ Cache cleared

Finding Your AdGuard Home Device

If you don't know your AdGuard URL:

Router admin panel — Look for a device named "AdGuard Home" or check for port 3000
Local network scan — Use nmap or check "Connected Devices"
If running on same machine — Default is http://localhost:3000
mDNS/Bonjour — Try http://adguard-home.local:3000 (depends on network)

Filtering Rules Syntax

AdGuard uses a DNS filtering rule syntax:

Rule	Effect
`\`	\	example.com^	Block example.com and subdomains
`@@\`	\	example.com^	Allow example.com (exception/whitelist)
example.com	Block exact domain only
`\`	\	ad.example.com^	Block only ad.example.com

See API Reference for complete syntax.

Common Scenarios

Allow a site that's blocked by accident

bash

adguard.sh allow my-bank.com

Block a known malware domain

bash

adguard.sh block malicious-tracker.xyz

Check if a domain is being filtered

bash

adguard.sh check ads.google.com

View today's statistics

bash

adguard.sh status

Temporarily disable filtering (e.g., for troubleshooting)

bash

adguard.sh toggle

Troubleshooting

Error: Failed to authenticate → Check ADGUARD_PASSWORD is correct and set → Verify ADGUARD_URL points to the right IP and port

Error: API call failed (HTTP 401) → Authentication failed, check credentials

Rules don't take effect → Run adguard.sh cache-clear to flush DNS cache → Wait 5+ minutes for clients to refresh their cache → Restart your device's network connection

Can't connect to AdGuard → Verify device is on the same network → Check firewall isn't blocking port 3000 → Ping the device: ping

Advanced: Batch Operations

Block multiple domains:

bash

for domain in tracker1.com tracker2.com tracker3.com; do
    adguard.sh block "$domain"
done

Check multiple domains:

bash

for domain in example.com test.org my-site.net; do
    echo "Checking $domain..."
    adguard.sh check "$domain"
done

API Reference

See references/api.md for complete AdGuard Home API documentation.

Installation

Terminal bash


openclaw install adguard

Copied!

💻Code Examples

./adguard.sh block malware.ru

adguardsh-block-malwareru.txt

## Configuration

Set environment variables for your AdGuard instance:

export ADGUARD_PASSWORD="your_admin_password" # REQUIRED

export-adguardpasswordyouradminpassword--required.txt

Add to `~/.bashrc` or `~/.zshrc` for persistence.

### Config File Alternative

Create `~/.adguard/config.json` (optional):

}

.txt

Then set `ADGUARD_PASSWORD` separately for security.

## Commands

### check `<domain>`

Check if a domain is currently blocked or allowed.

# ✓ example.com is NOT blocked (allowed)

--examplecom-is-not-blocked-allowed.txt

### allow `<domain>` | whitelist `<domain>`

Add a domain to the allowlist (whitelist). Creates an exception rule that overrides blocklists.

# Action: allow

-action-allow.txt

### block `<domain>` | blacklist `<domain>`

Add a domain to the blocklist. Creates a custom blocking rule.

# Action: block

-action-block.txt

### status | stats

Display DNS filtering statistics and protection state.

# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

-.txt

### toggle | protection

Enable or disable DNS protection. Useful for temporarily disabling filtering.

# ✓ Protection is now false

--protection-is-now-false.txt

### cache-clear

Clear the DNS cache to apply rule changes immediately.

# ✓ Cache cleared

--cache-cleared.txt

## Finding Your AdGuard Home Device

If you don't know your AdGuard URL:

1. **Router admin panel** — Look for a device named "AdGuard Home" or check for port 3000
2. **Local network scan** — Use `nmap` or check "Connected Devices"
3. **If running on same machine** — Default is `http://localhost:3000`
4. **mDNS/Bonjour** — Try `http://adguard-home.local:3000` (depends on network)

## Filtering Rules Syntax

AdGuard uses a DNS filtering rule syntax:

| Rule | Effect |
|------|--------|
| `\|\|example.com^` | Block example.com and subdomains |
| `@@\|\|example.com^` | Allow example.com (exception/whitelist) |
| `example.com` | Block exact domain only |
| `\|\|ad.example.com^` | Block only ad.example.com |

See [API Reference](references/api.md) for complete syntax.

## Common Scenarios

### Allow a site that's blocked by accident

adguard.sh toggle

adguardsh-toggle.txt

## Troubleshooting

**Error: Failed to authenticate**
→ Check `ADGUARD_PASSWORD` is correct and set
→ Verify `ADGUARD_URL` points to the right IP and port

**Error: API call failed (HTTP 401)**
→ Authentication failed, check credentials

**Rules don't take effect**
→ Run `adguard.sh cache-clear` to flush DNS cache
→ Wait 5+ minutes for clients to refresh their cache
→ Restart your device's network connection

**Can't connect to AdGuard**
→ Verify device is on the same network
→ Check firewall isn't blocking port 3000
→ Ping the device: `ping <ip>`

## Advanced: Batch Operations

Block multiple domains: