jmagar AdGuard
DNS-level ad blocking and network filtering. Talk to it directly over the AdGuard Home control API (served under /control, HTTP Basic auth).
How to call it
Prefer scripts/adguard-api.sh for common read-only calls. It sources the
plugin-generated config first, then the environment and legacy ~/.lab/.env,
keeps the Basic auth password out of output, and exposes
status, stats, querylog, filtering, and check-host.
Configure adguard_url, adguard_username, and the sensitive
adguard_password in Claude plugin settings or Gemini extension settings. The
SessionStart/ConfigChange hook writes
${XDG_CONFIG_HOME:-~/.config}/lab-adguard/config.env with mode 600.
Read the base URL and credentials without printing secrets:
source "${XDG_CONFIG_HOME:-$HOME/.config}/lab-adguard/config.env" 2>/dev/null || source ~/.lab/.env
: "${ADGUARD_URL:?missing ADGUARD_URL}"
: "${ADGUARD_USERNAME:?missing ADGUARD_USERNAME}"
: "${ADGUARD_PASSWORD:?missing ADGUARD_PASSWORD}"
AUTH=(-u "$ADGUARD_USERNAME:$ADGUARD_PASSWORD")
Auth is HTTP Basic (-u user:pass). Never echo the password.
Use
~/.lab/.envonly as a local migration fallback; prefer Claude/Gemini settings.
Common operations
| Intent | Request |
|---|---|
| Server status + version + running state | curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/status" |
| DNS query statistics | curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/stats" |
| Search the query log | curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/querylog?search=<term>&limit=50" |
| Filtering status / rule lists | curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/filtering/status" |
| Check whether a host is blocked | curl -sS "${AUTH[@]}" "$ADGUARD_URL/control/filtering/check_host?name=<host>" |
The version string and running state are fields inside GET /control/status (there is no separate version endpoint). Full API reference: https://github.com/AdguardTeam/AdGuardHome/blob/master/openapi/openapi.yaml.
Configuration
ADGUARD_URL, ADGUARD_USERNAME, and ADGUARD_PASSWORD come from plugin
settings, environment variables, or the legacy ~/.lab/.env fallback. Verify
connectivity:
curl -sS -o /dev/null -w 'HTTP %{http_code}\n' "${AUTH[@]}" "$ADGUARD_URL/control/status"
When NOT to use this skill
- The user is asking about a different homelab service — load that service's skill instead.
- The user wants to change filtering rules or protection settings — those are mutating
POST /control/*endpoints; confirm intent first and consult the OpenAPI reference for the exact body.