Agent skill · operations · affaan-m
homelab-pihole-dns
Pi-hole installation, blocklist management, DNS-over-HTTPS setup, DHCP integration, local DNS records, and troubleshooting broken DNS resolution on a home network. Use when the task explicitly involves Pi-hole — installing it, managing blocklists, configuring DoH or DHCP, adding local DNS records, or diagnosing DNS resolution with Pi-hole in the path.
Why this skill is useful
Provides specific commands and configurations for setting up Pi-hole, which the AI may not reliably generate on its own.
What it needs
Requires docker installed locally. About 5k tokens when loaded. Last updated 2026-08-06. 238,342 stars on the source repository.
What this skill does
Homelab Pi-hole DNS Pi-hole is a network-wide DNS ad blocker that runs on a Raspberry Pi or any Linux host. Every device on your network gets ad and malware domain blocking automatically — no browser extension needed. When to Use Installing Pi-hole on a Raspberry Pi or Linux host Configuring Pi-hole as the DNS server for a home network Adding or managing blocklists Setting up DNS-over-HTTPS (DoH) upstream resolvers Creating local DNS records (e.g. nas.home.lan, pi.home.lan) Troubleshooting devices that lose internet access after Pi-hole is installed Running Pi-hole alongside or instead of DHCP How Pi-hole Works Installation Docker (Recommended) Docker is the easiest way to install Pi-hole and makes updates and backups straightforward. Replace <pinned-release-tag> with a current Pi-hole release tag before deploying. Avoid latest for long-lived DNS infrastructure so upgrades are deliberate and reviewable. Set PIHOLEWEBPASSWORD in a .env file next to docker-compose.yml, chmod it to 600, and keep it out of git — do not put the password directly in the compose file. Access web admin at: http://<pi-ip>/admin Bare-Metal Install (Raspberry Pi OS / Debian / Ubuntu) Pi-hole requires a static IP before installing. Pointing Your Network at Pi-hole Blocklist Management DNS-over-HTTPS Upstream DNS-over-HTTPS encrypts your DNS queries so your ISP cannot see what sites you resolve. Local DNS Records Make your services reachable by name (e.g. nas.home.lan, grafana.home.lan). Domain name note: .home.lan is widely used in homelabs and works in practice. The IETF-reserved suffix for local use is .home.arpa (RFC 8375) — use that to follow the standard. Avoid .local for Pi-hole DNS records as it conflicts with mDNS/Bonjour. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills affaan-m/homelab-pihole-dns--b89050