Skip to main content

AdGuard Home integration for Gladys Assistant

AdGuard Home integration for Gladys Assistant

Control AdGuard Home DNS protection and follow its blocking statistics in Gladys.

View on GitHubAll external integrations

Requires Gladys 5.1 or later. The dashboard widgets and scene actions of this integration ship with Gladys 5.1; on an earlier version the integration cannot be installed.

Control the DNS protection of your AdGuard Home server from Gladys and follow its blocking statistics: switches for the protection and its filters, 24-hour counters, two dashboard widgets and two scene actions (timed pause, blocking of services such as YouTube or TikTok).

Requirements​

  • An AdGuard Home server reachable over the network from the machine running Gladys.
  • The account you use to log in to the AdGuard Home web interface. If your AdGuard Home runs without authentication, no account is needed.

Configuration​

Open the integration's configuration screen and fill in:

FieldDescription
AdGuard Home addressThe address of the web interface, the one you open in your browser, port included: for example http://192.168.1.10:3000, or https://adguard.example.com behind a reverse proxy. http:// is assumed when omitted.
UsernameYour AdGuard Home login. Leave empty if AdGuard Home has no authentication.
PasswordThe matching password. Leave empty if AdGuard Home has no authentication.
Refresh frequencyHow often AdGuard Home is read: 30 seconds, 1 minute (default) or 5 minutes.

Then click Test the connection. On success it answers Connected to AdGuard Home <version>.; otherwise it shows one of the messages listed under "Troubleshooting" below.

Prefer the local IP address of the machine running AdGuard Home to localhost or 127.0.0.1: the integration runs in its own container, where localhost may not point to that machine. Do not put the username and password in the address itself.

The AdGuard Home device​

Once the connection works, an AdGuard Home device appears automatically in the Discovery tab of the integration, with no scan needed. Create it to get its features:

FeatureTypeDescription
DNS protectionSwitchTurns the whole AdGuard Home filtering on or off (off until you turn it on again).
Safe browsingSwitchAdGuard's blocking of malware and phishing domains.
Parental controlSwitchAdGuard's blocking of adult content.
Safe searchSwitchForces safe search on search engines; the per-engine choices of AdGuard are kept.
DNS queries (24 h)SensorNumber of DNS queries over the last 24 hours.
Blocked queries (24 h)SensorNumber of blocked queries over the last 24 hours.
Blocked queries ratio (24 h)SensorShare of blocked queries over the last 24 hours, in %, rounded to a whole number.
Average processing timeSensorAverage time AdGuard Home takes to answer a query, in milliseconds, as it reports it.

The switches reflect the real state of AdGuard Home: a change made from its web interface shows up in Gladys at the next refresh. After a command sent from Gladys, the values are refreshed right away.

About "24 h". AdGuard Home reports its statistics per hour or per day depending on its statistics retention setting. With hourly statistics, the figures cover the last 24 hours (sliding window). With daily statistics, AdGuard gives no hourly detail: the figures are those of the current day, and the chart of the Overview widget is not shown.

Dashboard widgets​

Add them from the dashboard editor.

Overview​

  • Three tiles: Queries (24 h), Blocked (24 h) and Blocked share (24 h) (with one decimal, highlighted as a warning above 50 %).
  • A Last 24 hours chart of queries and blocked queries per hour (only with hourly statistics, see above).
  • Status rows: Protection (On, Off, or "Paused until 16:30" in the time zone of your Gladys instance), Safe browsing, Parental control, Safe search and the AdGuard Home version.
  • A button: Pause 10 min while the protection is on, Resume protection while it is paused or off. AdGuard Home resumes the protection by itself at the end of a pause.

Top lists​

Choose the list in the widget settings: Most blocked domains, Most queried domains or Most active clients (client name and IP address). Up to 10 entries with their count.

These lists come from AdGuard Home's own rankings and cover its whole statistics retention period (for example 24 hours or 7 days), not 24 hours.

Scene actions​

Pause DNS protection​

Pauses the protection for 30 seconds, 1 minute, 10 minutes (default), 1 hour, 8 hours or 24 hours. AdGuard Home resumes it by itself.

Outputs, usable as {{…}} variables in the following actions of the scene:

  • Resume time (HH:MM) (resume_time): when the protection resumes, in the time zone of your Gladys instance (for example 16:30), ready for a notification message;
  • Protection resumes at (ISO date) (resume_at): the same instant as an ISO 8601 date with the local UTC offset (for example 2026-09-26T16:30:00+02:00).

Block or unblock services​

  • Operation: Block or Unblock.
  • Services: one or more of 25 services: YouTube, TikTok, Instagram, Facebook, Snapchat, X (Twitter), Reddit, Pinterest, WhatsApp, Discord, Telegram, Netflix, Disney+, Prime Video, Twitch, Spotify, Roblox, Minecraft, Epic Games (Fortnite), Steam, PlayStation, Xbox Live, Nintendo, League of Legends, ChatGPT.
  • Client (name, IP or ClientID, empty for the whole network):
    • empty: the global list of blocked services of AdGuard Home is changed, for the whole network;
    • otherwise: only that client is changed. It must be a persistent client, declared in AdGuard Home under Settings > Client settings, and is matched by its name (case-insensitive) or one of its identifiers (IP, ClientID…). The client is switched to its own list of blocked services, starting from the global list if it was following it: later changes of the global list no longer apply to it. To make it follow the global list again, tick "Use global blocked services" in its AdGuard Home settings.

Services outside the list above, blocked from the AdGuard Home web interface, are kept, and so is the blocking schedule.

Output: Services now blocked (blocked_services), the AdGuard identifiers of the services blocked after the change, comma-separated (for example youtube, tiktok).

If an action fails (AdGuard Home unreachable, unknown client…), the error is written in the scene logs and the rest of the scene carries on.

Troubleshooting​

Error messages appear in the integration's connection status, under the Test the connection button, and in the widgets.

"Enter the AdGuard Home address in the configuration." Fill in AdGuard Home address.

"The AdGuard Home address is not valid: use http(s)://host:port, without username or password in it." The address is not an http:// or https:// address, or it contains a username and password: put those in their own fields.

"AdGuard Home refused the username or password. Check them in the integration settings. Polling is suspended until then." Check the username and password (those of the AdGuard Home web interface), then save the configuration or click Test the connection. Read "Locked out after wrong passwords" below.

"AdGuard Home cannot be reached. Check its address and that it is running." AdGuard Home is stopped, the address or port is wrong, or a firewall blocks the connection. Use the address you open in your browser, with the port of the web interface (not the DNS port 53).

"AdGuard Home did not answer in time. Check that it is running and that the address is right." No answer within 10 seconds: often a wrong IP address, or a firewall that silently drops the connection.

"The HTTPS certificate of AdGuard Home is not trusted. Use its http:// address or a valid certificate." AdGuard Home (or your reverse proxy) uses a self-signed certificate. Use its http:// address on your local network, or a certificate issued by a recognized authority.

"The address does not lead to the AdGuard Home API (unexpected answer). Check the address, the username and the password." The address answers with a web page instead of AdGuard Home: another application on that port, or the login page of a reverse proxy (Authelia, Authentik…). Use the direct address of AdGuard Home, or let the /control/ path through the proxy without its login.

"AdGuard Home answered with an error (HTTP …). Check that it is up to date." AdGuard Home refused the request: update it to a recent version. A 404 can also mean that the address leads to another web server.

"Unexpected error while talking to AdGuard Home. Check the integration logs." Look at the integration logs in Gladys, and report the problem if it persists.

"No data from AdGuard Home yet. If this lasts, check the address and the account in the integration settings." Shown by the widgets until the first successful read. Click Test the connection to see the actual error.

When a read fails after a successful one, the widgets keep showing the last data with a Last update: Failed, data may be outdated row.

Locked out after wrong passwords​

AdGuard Home blocks an IP address after several failed logins (by default 5 attempts, then 15 minutes), its web interface included: during that time the machine running Gladys, and anything sharing its address, cannot log in to AdGuard Home, even with the right password.

To avoid causing this, the integration stops polling as soon as AdGuard Home refuses the username or password, instead of retrying at every refresh. Polling resumes when you save the configuration or click Test the connection. If you already tried several times, wait 15 minutes before testing again.

Privacy​

  • The Top lists widget shows the domains visited on your network and the names and IP addresses of your devices to anyone who can see the dashboard. Only add it to dashboards whose viewers may see that.
  • The password is stored by Gladys as a secret and is only sent to your AdGuard Home server. The integration talks to nothing else.

Configuration settings​

These are the settings AdGuard Home asks for in its configuration screen in Gladys.

SettingTypeRequiredDescription
Connect to AdGuard HomesectionNoEnter the address of the AdGuard Home web interface (the one you open in your browser) and the account you log in with.
AdGuard Home addressstringYes
UsernamestringNo
PasswordsecretNo
Refresh frequencyselectNo

How to install AdGuard Home in Gladys​

  1. In Gladys, open Integrations: AdGuard Home appears in the catalog, next to the native integrations, with a community badge.
  2. Click Install. Gladys pulls the Docker image (ghcr.io/cicoub13/gladys-adguard-home:0.1.1), starts it in a sandbox isolated from the core, and generates the integration's interface (devices, discovery and configuration).
  3. Open the Configuration screen of the integration, fill in the settings, and save.
  4. You can also install it directly from its repository URL: https://github.com/cicoub13/gladys-adguard-home.

AdGuard Home requires Gladys >=5.1.0. The catalog inside Gladys refreshes every hour, so a new version becomes available at most one hour after its release.

Not running Gladys yet? It is free and open source: follow the installation guide to get started.

About external integrations​

AdGuard Home is an external integration: a community integration packaged as a Docker container and published on GitHub, that Gladys installs in one click and runs in a sandbox isolated from its core. It is published and maintained by cicoub13, not by the Gladys core team.

Subscribe to the Gladys Assistant newsletter

A few emails per month about new releases and project news. Sent by Pierre-Gilles Leymarie, founder of the project. Unsubscribe anytime 🙂
Last updated on