Add a DNS filter to AdGuard Home without guessing.

Before you start

You need a working AdGuard Home instance and administrator access to its web interface. You also need a way to copy a file onto the machine that runs AdGuard Home if you plan to use a local path. If AdGuard Home runs in a container, remember that “local” means inside that container's filesystem, not your laptop.

Generate an AdGuard Home configuration first. Download the file somewhere you can find it. Do not rename it to a binary format; it is a plain UTF-8 text file.

Menu labels and local-file behavior have changed across AdGuard Home releases. Where this guide says “labels may vary,” check the same setting in your version rather than assuming an old screenshot is current.

What the CleanWeb file contains

An AdGuard Home output uses native AdGuard DNS rule syntax. Each rule looks like ||example.org^, which targets the hostname and its subdomains according to AdGuard's filtering engine. The generated file also starts with comments containing the target, strength, generation time, source category names, upstream links, and license notes.

! CleanWeb configuration
! Target: Privacy | Strength: Balanced | Format: AdGuard Home
! Generated: [timestamp]
! Domains: [count]
! Sources:
!   - The Block List Project — Tracking
!     https://blocklistproject.github.io/Lists/tracking.txt
!     License: Unlicense (repository); file header: MIT

||example.org^

The example above is a syntax illustration. Your downloaded file contains the actual sampled hostnames and its own complete source header. CleanWeb does not add cosmetic filter rules, scriptlets, or browser-extension syntax to a DNS list.

Add the filter to AdGuard Home

1. Copy the file to the AdGuard Home machine. Choose a location that survives restarts. If you use Docker, copy it into a mounted volume rather than the container's temporary filesystem.
2. Open the admin interface and find the DNS blocklists. In current releases this is under Filters → DNS blocklists. Open Add blocklist, then choose the custom-list option. UI wording varies by release.
3. Choose a local path or a URL. A local path is an absolute path to the file as seen by AdGuard Home. A URL must point to the raw text file, not an HTML page. CleanWeb does not host your generated file; a URL option means you arrange private hosting yourself.
4. Respect local-path restrictions. Recent AdGuard Home versions restrict local paths to configured safe directories. If the interface rejects a path or reports an error mentioning safe patterns, do not weaken your filesystem permissions blindly. Either place the file in an approved directory according to your version's documentation, or host it privately and use the URL field.
5. Name the list and save it. Use a descriptive name such as “CleanWeb Privacy Balanced.” Make sure the blocklist is enabled.
6. Trigger an update if the list is local. AdGuard Home may copy or cache a local filter. After placing or replacing the file, use the update action for that list so the new contents are read. Do not assume that overwriting the file immediately changes the active ruleset.

Avoid exposing the AdGuard Home admin interface to the public internet. If you host the filter file yourself, limit access to the local network or trusted clients and use HTTPS where your setup supports it.

Verify what loaded

• Check the rule count displayed beside the filter list. It should be plausible for the number of domains in your file. A successful save does not prove the content was read.
• Use AdGuard Home's query log with a device that uses this resolver. Look up a hostname that you know is in the list and confirm the filtering decision. Test with a domain you can safely fail to resolve.
• Confirm that the client is actually using AdGuard Home. Devices with a manual DNS setting, a VPN, or browser-level secure DNS can bypass your network resolver.

Do not treat “the UI turned green” as proof that every device is filtered. DNS is a per-client setting.

Updating the list

Generate a new file, download it, and read the header. If you use a local path, replace the file and update the filter list in AdGuard Home. If you use a URL, publish the new file at the same URL and use the list's update action.

Before replacing a working list, compare the old and new text with the rule diff. A large number of unexpected removals is a reason to stop and inspect the file, not a reason to click through faster.

Troubleshooting

The local path is rejected

Check that the path is absolute, correct from inside the AdGuard Home environment, and permitted by your version's safe-path configuration. Container paths are a common source of confusion. If your setup does not allow local files, use a private URL instead of disabling safeguards.

The list shows zero rules or an old count

Validate the downloaded text first. Then confirm that the entry points to the intended file and trigger an update. If the count still looks wrong, remove and re-add the list rather than editing AdGuard Home's internal files by hand.

A site or app breaks

Disable the CleanWeb list to confirm it is the cause. If it is, add a targeted exception for the affected hostname using AdGuard's allowlist or custom-rule facilities, then test again. Do not disable domain verification or other security controls to make one site work.

Only some devices are filtered

AdGuard Home only filters clients that send DNS queries to it. Check each device's DNS settings, your router's DHCP advertisement, and any VPN or private DNS feature that can override the resolver.

Limits and safety

DNS filtering acts on hostnames. It cannot inspect paths, page content, or encrypted in-app traffic, and it cannot protect a device that bypasses AdGuard Home. CleanWeb's snapshots are bounded and may contain false positives from upstream lists. A syntax check is not a safety review for your particular network.

Keep a recovery path: access to the AdGuard Home admin interface from a device that does not rely on the filter, and the ability to disable the list. Review the sources and licenses on the sources page before redistributing a generated file.

For the exact rule grammar, defer to AdGuard's official DNS filtering syntax documentation. For local file handling, use the documentation that matches your installed version.