AdGuard Home

The AdGuard Home integrationIntegrations connect and integrate Home Assistant with your devices, services, and more. [Learn more] allows you to control and monitor your AdGuard Home instance in Home Assistant.

AdGuard Home is a network-wide software for blocking advertisements and tracking. It provides DNS-level protection, automatically covering all home devices without requiring client-side software. When you use AdGuard Home as your DNS server, it blocks advertisements, trackers, and malicious domains for all devices on your network.

Prerequisites

Before setting up the AdGuard Home integration, ensure you have:

1. AdGuard Home installed and running on your network
2. The IP address or hostname of your AdGuard Home instance
3. Admin access to AdGuard Home

Configuration

To add the AdGuard Home service to your Home Assistant instance, use this My button:

Supported functionality

Sensors

This integration provides sensors for the following information from AdGuard Home:

• Number of DNS queries.
• Number of blocked DNS queries.
• Ratio (%) of blocked DNS queries.
• Number of requests blocked by safe browsing.
• Number of safe searches enforced.
• Number of requests blocked by parental control.
• Total number of active filter rules loaded.
• Average response time of AdGuard’s DNS server in milliseconds.

Switches

The integration provides switches to control AdGuard Home features:

• AdGuard protection: Master switch that controls all AdGuard features
• Filtering: Enables DNS filtering using blocklists
• Safe browsing: Blocks known phishing and malware sites
• Parental control: Blocks adult content
• Safe search: Enforces safe search on search engines
• Query log: Records DNS queries for statistics

These switches enable powerful automations. For example, you could automatically enable parental controls during school hours or disable ad blocking for specific time periods.

The AdGuard protection switch acts as a master control. When turned off, it bypasses all AdGuard features regardless of individual switch states.

Actions

The integration provides actionsActions are used in several places in Home Assistant. As part of a script or automation, actions define what is going to happen once a trigger is activated. In scripts, an action is called sequence. [Learn more] to manage filter subscriptions in AdGuard Home. Use these actions in automations to dynamically control content filtering based on time, presence, or other conditions.

For example, you could create automations that:

• Block social media during work hours
• Enable strict filtering when guests connect to your network
• Temporarily disable filtering for specific downloads

Action adguard.add_url

Adds a new filter subscription to AdGuard Home.

Action adguard.remove_url

Removes a filter subscription from AdGuard Home.

Action adguard.enable_url

Enables a previously disabled filter subscription.

Action adguard.disable_url

Temporarily disables a filter subscription without removing it.

Action adguard.refresh

Refreshes all filter subscriptions to get the latest blocking rules.

By default, force is false. AdGuard Home normally throttles filter updates to reduce server load. Use forced updates sparingly.

Examples

Block social media during work hours

This automation blocks social media sites during business hours:

automation:
  - alias: "Block social media during work"
    triggers:
      - trigger: time
        at: "09:00:00"
    actions:
      - action: adguard.add_url
        data:
          name: "Social media blocklist"
          url: "https://raw.githubusercontent.com/example/social-media-blocklist/main/list.txt"
      - action: adguard.refresh

  - alias: "Unblock social media after work"
    triggers:
      - trigger: time
        at: "17:00:00"
    actions:
      - action: adguard.remove_url
        data:
          url: "https://raw.githubusercontent.com/example/social-media-blocklist/main/list.txt"

Enable strict filtering when guests arrive

Automatically enable all protection features when guests connect to your network:

automation:
  - alias: "Enable strict filtering for guests"
    triggers:
      - trigger: state
        entity_id: group.guest_devices
        from: "not_home"
        to: "home"
    actions:
      - action: switch.turn_on
        target:
          entity_id:
            - switch.adguard_parental_control
            - switch.adguard_safe_browsing
            - switch.adguard_safe_search

Monitor DNS performance

Send a notification if DNS response time exceeds threshold:

automation:
  - alias: "Alert on slow DNS"
    triggers:
      - trigger: numeric_state
        entity_id: sensor.adguard_average_processing_speed
        above: 50
    actions:
      - action: notify.mobile_app
        data:
          title: "DNS Performance Alert"
          message: "AdGuard DNS response time is {{ states('sensor.adguard_average_processing_speed') }}ms"

Data updates

The AdGuard Home integration polls for updates every 10 seconds to provide near real-time statistics and ensure switch states remain synchronized.

Troubleshooting

Integration fails to connect

Symptom: “Cannot connect to AdGuard Home”

When setting up the integration, you receive a connection error.

Resolution

1. Verify AdGuard Home is running:

   • Access the AdGuard Home web interface at http://YOUR_IP:3000.
   • Check the service status on your server.

2. Check network connectivity:

   • Ensure Home Assistant can reach the AdGuard Home instance.
   • Verify no firewall rules block port 3000.

3. Confirm credentials:

   • Test login via the AdGuard Home web interface.
   • Ensure you’re using admin credentials.

Sensors show unavailable

If sensors display as unavailable:

1. Check that Query log switch is enabled.
2. Verify AdGuard Home is processing DNS queries.
3. Ensure at least one device uses AdGuard Home as DNS server.

Actions fail with “Filter URL not found”

This error occurs when trying to enable, disable, or remove a non-existent filter URL. Verify the exact URL using the AdGuard Home web interface under Filters > DNS blocklists.

Removing the integration

This integration follows standard integration removal. After removal, your AdGuard Home instance continues running with its current configuration.

To remove an integration instance from Home Assistant

1. Go to Settings > Devices & services and select the integration card.
2. From the list of devices, select the integration instance you want to remove.
3. Next to the entry, select the three dots menu. Then, select Delete.