app-adguard-home: AdGuard Home as a Home Assistant Community App

A packaging layer around AdGuard Home, not a fork of it

The distinction to hold onto is that this repository is an add-on package, not the AdGuard Home project itself. The top-level listing makes that visible: .github/, .mdlrc, .yamllint, LICENSE.md, README.md, an adguard/ directory and an images/ directory. There is no source tree for a DNS server in here. The primary language of the repository is Jinja, which is the template language the Home Assistant add-on system uses to render configuration, rather than the Go in which AdGuard Home itself is written.

What the add-on does is take AdGuard Home, run it inside the Home Assistant add-on runtime, and give you a place to configure it from the same interface where you configure everything else on the platform. The upstream project is referenced in the About section, which describes AdGuard Home as a network-wide ad-and-tracker blocking DNS server with parental control capabilities, whose purpose is to let you control your entire network and all your devices without using a client-side program.

That last clause is the whole point of the mechanism. Blocking happens at the DNS resolver, so the moment your devices ask the resolver for an address, the resolver answers with a null address for the domains on the block list. Nothing has to be installed on the phone, the television or the guest laptop, and a device that joins the network is covered without further work.

The audience is a Home Assistant user who wants the filtering to apply to the whole household rather than to individual devices, and who would rather manage one add-on than run a separate server and point clients at it by hand.

The add-on directory holds the configuration and the documentation

The readme is deliberately short on configuration detail and points at the add-on directory instead. The link labelled as the full app documentation resolves to a file inside the adguard/ directory in the repository, at adguard/DOCS.md, and the file listing confirms that the adguard directory is where the substance of this package lives.

That layout is standard for the Home Assistant add-on ecosystem. The add-on directory carries the metadata that describes the add-on to the platform, the configuration schema the user fills in from the add-on configuration panel, the startup and shutdown scripts that Home Assistant runs to start and stop the service, and the documentation file that the readme points at. The images/ directory at the root holds the artwork used for the add-on store listing, and the screenshot referenced in the readme.

The consequence for a reader is worth stating plainly. The readme in this repository is an index and a description, and if you want to know which options exist, which ports the add-on exposes, or how the persistent storage is laid out, you have to open the DOCS.md file and the configuration schema. That is where the substance is, and it is a deliberate split, since the add-on documentation is the version that matches the configuration schema and the rest of the add-on package.

The linting configuration in the repository, .mdlrc for markdown and .yamllint for YAML, tells you the add-on metadata and configuration files are validated in CI, which is how a Home Assistant add-on keeps its configuration schema consistent with the documentation.

Installing the app and finding its web interface

There is no install command in this repository, and that is not an omission. A Home Assistant Community App is installed through the platform rather than through a shell.

The path is the Home Assistant add-on store, where this app appears alongside the other apps in the same collection, and from there the add-on is installed, started and configured from the Home Assistant user interface. The readme links the community forum thread for this specific add-on, which is where the setup questions and their answers live, and the documentation file in the adguard directory is the reference for the options once it is running.

Two things follow from the DNS design that are worth planning before you start. The first is that the filtering only takes effect for clients that use your resolver. Devices that hardcode a public DNS server, such as a smart television with a baked-in configuration or a phone with a private relay, will bypass it entirely. The second is that this changes the behaviour of every DNS lookup on the network, including the ones you depend on for work, so a misconfigured block list shows up as a site that will not load rather than as an error message.

Neither is a defect in the add-on. They are properties of doing filtering at the resolver, and the parental control side of AdGuard Home, which blocks adult content, applies with the same mechanism and the same caveat.

The web interface is where the filtering is configured

The About section credits AdGuard Home with providing a web interface to easily manage the filtering process and its settings, and that interface is the practical centre of the add-on.

This is the piece of the design that makes the package worth having in a Home Assistant setup. You get AdGuard Home's own management UI, running as part of an add-on, rather than a set of knobs in the Home Assistant configuration panel. The filtering rules, the query log and the settings live where AdGuard Home puts them, which means the interface is the upstream one and the documentation for it is the upstream documentation.

The design consequence is a split of responsibility that is easy to misunderstand. The add-on handles packaging, configuration and lifecycle inside Home Assistant. AdGuard Home handles the actual blocking, the DNS service and its web interface. When something does not filter, the question of whether the fault lies in the add-on configuration or in AdGuard Home itself becomes a real debugging step, and the answer depends on where in that chain the problem is.

The readme also flags the point that matters for a home network, that this does not require a client-side program. Every device that resolves through this server is covered, including devices you did not configure and cannot configure, which is the practical difference between this and a browser extension or a per-device app. It is also the reason the parental control feature has reach it would not have with client-side blocking.

Version cadence, maintenance signalling and what the badges tell you

The release history shows steady iteration rather than a one-off package. The versions are v6.3.0 on 2026-09-18, v6.2.1 on 2026-08-19 and v6.2.0 on 2026-06-11, and the last push to the repository was on 2026-10-22.

The readme carries a set of status badges that are worth reading as signals rather than decoration. There is a project stage badge, and it reads as production ready, which is the maintainer's own assessment of the add-on's fitness. There is a project maintenance badge, and the one in the repository points at a 2026 status, which is how this collection of add-ons communicates ongoing upkeep to someone browsing the store.

There is also a release badge pointing at the GitHub releases and a commit activity badge, and the readme links a Docker Hub repository for the image, which is where the container itself is published. The Docker Hub link is a small but useful detail, because it tells you the add-on is built as a container image and that the image is publicly available, which is what lets you run the same AdGuard Home build outside Home Assistant if you ever want to.

The maintainer is Franck Nijhof, credited as the original setup of this repository, with copyright running from 2019 to 2026. That range is the clearest evidence of the project's age: this add-on has been maintained across a very large part of the Home Assistant add-on era, and the version number in the sixes reflects that.

Where this add-on is the wrong answer

There are three situations where packaging AdGuard Home inside Home Assistant is not the move.

The first is when you need filtering that DNS cannot deliver. Blocklists work on domain names, so a resolver-based approach cannot stop an advertisement served from the same domain as the content, and it cannot act on connections to a raw IP address. If your requirement is content-level blocking, per-device policies that differ by who is using the device, or reporting about which device is generating traffic, you want a filtering solution that operates at those layers instead.

The second is when Home Assistant is not the thing you want in the DNS path. This add-on makes AdGuard Home a dependent of your Home Assistant instance, and the instance becomes part of the network's name resolution path. If you run Home Assistant on hardware you also use for other things, or you would rather have name resolution be a separate, always-on appliance, then a standalone AdGuard Home deployment, which the same maintainer publishes as a separate image on Docker Hub, is the more honest arrangement.

The third is a scale mismatch. A home network is the stated use case, and the upstream project's scope is a network-wide DNS server with a web interface. Running it across a large corporate network with thousands of clients, with the policies and reporting that implies, is a different engineering problem.

One more limit is inherent rather than incidental. The filter lists have to be maintained by someone, and the add-on does not change that. The blocking is only as current as the list it is configured to use.

Editorial conclusion

Adopt this app if you already run Home Assistant and want network-wide ad and tracker blocking with parental control on a device you manage yourself, and you are comfortable pointing your clients at a DNS server. Do not adopt it if you want a product with per-device filtering policies, or if you need blocking that is independent of DNS resolution, since the filtering happens at the resolver. Verify first that the readme-linked documentation in the adguard directory matches the version you install, that the maintenance status badge in the repository reflects what you need from a network component, and that the DNS change you make on your clients is one you can roll back.

Frequently asked questions

Official sources

1. hassio-addons/app-adguard-home on GitHub
2. Issues
3. License: MIT
4. README
5. Releases