Pi-hole and AdGuard Home block ads and trackers for every device on your network by answering DNS lookups. Home Assistant has an official integration for each one. Once connected, you can see blocking statistics on a dashboard, pause filtering with a switch and build automations around the results. This guide covers both integrations, where to run the DNS server, and the setup mistakes that let traffic skip the blocker.
Run the DNS server on its own device
Run Pi-hole or AdGuard Home on a separate device, container or VM, not on the same machine as Home Assistant. Home Assistant restarts and updates regularly. If the DNS server runs there, every restart also interrupts DNS for the whole network.
If you want redundancy, run two blocking servers. Don’t pair a blocking server with a public DNS server, because clients may use either one.
For hardware, see is a Raspberry Pi 4 overkill for Pi-hole?. For installation, see how to set up Pi-hole.
Connect Pi-hole to Home Assistant
Go to Settings > Devices & services, select Add integration and choose Pi-hole. Enter the Pi-hole host and an app password. Pi-hole v6 uses a newer API, so use a Home Assistant release that supports it.
The integration adds sensors for ads blocked today, DNS queries today, percent blocked, domains on blocklists and unique clients. It also adds a switch that turns blocking on or off.
The pi_hole.disable action pauses blocking for a set time. Its duration field uses a time format such as 00:05:00. A dashboard button that pauses blocking for five minutes is a common setup. It’s useful when a site breaks because of a blocked domain.
action: pi_hole.disable
data:
duration: "00:05:00"
If the editor asks for a target, choose your Pi-hole entity.
A notification when percent blocked drops to zero can help you spot a problem. The drop can mean that devices have stopped using Pi-hole, or that the server has a fault.
Home Assistant’s recorder keeps most state history for about 10 days by default. If you want longer history for these sensors, see how to log sensors in InfluxDB and Grafana.
Connect AdGuard Home to Home Assistant
AdGuard Home can run as a Home Assistant add-on from the Community Add-ons repository. The add-on route works only on Home Assistant OS. You can also run AdGuard Home on separate hardware or in a container.
AdGuard Home’s first-run setup wizard listens on port 3000. After setup, the admin interface uses the port you chose, commonly 80. Use that port when you add the integration.
The integration provides a set of sensors, including DNS queries, blocked queries, percentage blocked, safe browsing and parental control blocks, and average response time. It also provides switches for protection, filtering, safe browsing, parental control, safe search and the query log.
It adds actions for managing filter lists: add, remove, enable, disable and refresh. You can call them from automations, for example to refresh lists on a schedule.
Choosing between them
Both block at the network level, and both integrate with Home Assistant. The main differences are these:
- Pi-hole is a blocklist-focused project with a long history and a large community. Its Home Assistant add-on was discontinued some years ago, so run Pi-hole on its own device or container and connect it with the integration. Encrypted or recursive upstream DNS needs a companion such as cloudflared or Unbound.
- AdGuard Home supports encrypted upstream DNS (DoH, DoT and DoQ) natively. Reviewers often point to its built-in service blocking and parental controls. Its DHCP server has been described as experimental, so check the current documentation before you rely on it.
Either tool works. Pick the one whose features match your needs, and set it up carefully.
Mistakes that bypass blocking
- Adding a public DNS server as a secondary. Clients choose a server, so some lookups skip your blocker.
- Leaving browser DNS-over-HTTPS on. Browsers with DoH enabled can skip both tools. Turn it off in the browser settings, or manage it with your network policy.
- Leaving IPv6 DNS open. Routers can advertise their own IPv6 DNS server, which lets devices skip yours. Check the router’s IPv6 DNS settings.
- Expecting YouTube and Twitch ads to be blocked. Those ads are served from the same domains as the video, so DNS blocking can’t reliably separate them.
Keep the admin pages private
Don’t expose port 53 or the admin interface to the internet. Open DNS servers can be abused in amplification attacks. Protect Pi-hole’s app password and Home Assistant’s tokens, and use a VPN if you need remote access.