Skip to content
AdminKit

Set up AdminKit's Home Assistant add-on for Protective DNS metadata

AdminKit's Home Assistant Supervisor add-on builds the DNS-over-HTTPS URL for AdminKit's L1 Protective DNS and serves per-device connection and blocked-query counts for Home Assistant's built-in rest sensor to poll. It is real, tested code that Netbase provides with a Protective DNS engagement — read on for what it does and how it is set up.

By AdminKit team, Netbase JSC · Updated

Key takeaways

  • The add-on is a small local service, not a resolver. It builds your Protective DNS DoH URL and serves per-device counts at /metadata and /dns-config on port 8099.
  • It needs a backend: the AdminKit L1 resolver and control-plane API that Netbase sets up and runs for you in a Protective DNS engagement. Netbase also provides the add-on’s files.
  • You install it as a local add-on, set api_key and site_slug, and read it from Home Assistant’s built-in rest and template sensors. No HACS or custom component is involved.
  • Per device it keeps only counts, a last-seen time and the most recently blocked domain, in memory. Raw client IPs and full query logs are dropped.

What does this add-on actually do?

It turns your engagement details into router settings and Home Assistant data; it never answers DNS queries. This add-on sits at the intersection of Home Assistant automation and the DNS-focused tooling covered across AdminKit’s DNS cluster. This is a Home Assistant Supervisor add-on, not a DNS resolver itself: it is a client of AdminKit’s control plane (/v1/dns/*) and of the edge DoH convention AdminKit’s resolvers use (/dns-query/<site|device>/<id>). Concretely, it does three things:

  1. Builds the AdminKit DoH URL for your configured site (https://<dns host>/dns-query/site/<slug>) plus a plain-DNS fallback, and serves both at GET /dns-config on the add-on’s local port — the values you’d put in your router’s DNS-over-HTTPS / DNS settings. The URL format follows RFC 8484, the IETF standard defining DNS Queries over HTTPS, which is what makes it a value any DoH-capable router or client can use, not an AdminKit-specific convention. A DoH request carries an ordinary binary DNS message with the media type application/dns-message, which RFC 8484 registered in IANA’s media type registry.
  2. Polls the AdminKit control-plane API (GET /v1/dns/devices, GET /v1/dns/events) for your organization and aggregates, per device, a 24-hour connection count, a 24-hour blocked-query count, the last-seen timestamp and the most recently blocked domain — then serves that at GET /metadata.
  3. Does not store or forward raw client IPs, full DNS query logs, or anything beyond that aggregate.

The DNS host in the DoH URL is derived from api_url: the add-on replaces the first api. in that URL with dns., so the default https://api.adminkit.net gives https://dns.adminkit.net. If your api_url has no api. in it, the DoH URL uses the same host as the API. If DoH itself is new to you, our guide to DoH vs. DoT privacy trade-offs covers what it does and doesn’t hide.

What do you need before you start?

You need a Home Assistant install that runs the Supervisor, plus the Protective DNS backend. The add-on’s own code is complete and tested — generating config and serving /metadata and /dns-config all work in its own test suite. On its own, though, it is only a client: it needs an AdminKit L1 Protective DNS resolver (the DoH host your router actually queries) and the control-plane API (/v1/dns/*) it polls for device data. Both come with a Protective DNS engagement, which Netbase sets up and runs for your network — talk to our team to scope one. Without that backend, /dns-config and /metadata build correctly but have nothing to resolve against or pull device data from.

From the engagement you get three values: the control-plane URL (api_url), an API key scoped to your organization (api_key), and the slug of the site Netbase created for your network (site_slug). The add-on sends the key as a Bearer token on its two read-only requests and nowhere else.

On the Home Assistant side, Supervisor add-ons run as separate containers next to Home Assistant Core. That means Home Assistant OS or a Supervised install; a plain Home Assistant Container setup has no add-ons. The image is built on Home Assistant’s Python base images for amd64, aarch64 and armv7.

How do you install it as a local add-on?

You copy the folder into the Supervisor’s local add-on directory and install it from the store’s local section. Netbase provides the add-on’s files as part of a Protective DNS engagement (talk to our team). The add-on is not listed in the Supervisor add-on store, so install it as a local add-on:

  1. Copy the add-on’s files to /addons/adminkit_l1_dns on a Home Assistant OS/Supervised host — see Home Assistant’s own docs on testing local add-ons.
  2. In Home Assistant, go to Settings → Add-ons → Add-on Store → local add-ons and install it from there.
  3. Set the required options and start it (see the list below).

Home Assistant has since renamed add-ons to “apps” (Home Assistant OS common tasks). On current releases the folder is local_apps, reachable through the Samba share or Terminal & SSH app, and the menu path is Settings → Apps → Install app, then Check for updates in the top-right menu so a Local apps section appears (Your first app). The Supervisor builds the image on the device from the included Dockerfile; if the build fails, the Supervisor log under Settings → System → Logs says why.

Which options does the add-on take?

Five options, of which only api_key has no usable default. The Supervisor validates each against the type in the add-on’s schema before the add-on starts, and writes the result to /data/options.json (app options).

OptionTypeDefaultWhat it controls
api_urlurlhttps://api.adminkit.netAdminKit control-plane base URL.
api_keypassword""AdminKit API key for your org — required.
site_slugmatch(...)homeThe site this add-on reports and configures for.
poll_interval_secondsint(30,3600)300How often to re-poll devices and events.
http_portport8099Local port serving /metadata and /dns-config.

The site_slug pattern is ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$: lowercase letters, digits and hyphens, 1 to 63 characters, no hyphen at either end. It must match the /v1/dns/sites slug of the site Netbase created for you. The password type only hides the key in the form; it is still passed to the add-on as plain text inside its container.

Leave http_port at 8099 unless you have a reason. The add-on’s manifest maps container port 8099 to the host, so changing http_port moves the server to a port that mapping doesn’t cover (port mapping).

How do you point your network at AdminKit L1 DNS?

You copy the DoH URL from /dns-config into your router; the add-on can’t do it for you. The add-on cannot change your router’s settings for you — it has no credentials for your router. Once running, GET http://<addon-host>:8099/dns-config returns:

{
  "adminkit_l1_dns": {
    "doh_url": "https://dns.adminkit.net/dns-query/site/home",
    "fallback_resolvers": ["1.1.1.1", "1.0.0.1"],
    "note": "Set this DoH URL as your router's DNS-over-HTTPS resolver, or point device DNS at the fallback resolvers if DoH is unsupported."
  }
}

That is the output with the default api_url and site_slug; your values come from the engagement. The fallback resolvers are fixed in the add-on’s code and are not configurable. They are Cloudflare’s standard public resolver addresses, which Cloudflare’s 1.1.1.1 documentation describes as providing DNS lookups with no content filtering — so a device that falls back to them is not protected by Protective DNS blocking. To fetch it from a computer on the same LAN, use the Home Assistant host’s address (here a typical private LAN address):

curl -s http://192.168.1.20:8099/dns-config

Put doh_url in your router’s “DNS over HTTPS” / “Private DNS” field if it supports one. A router without DoH support should instead run the OpenWrt package (which also attributes queries per device), or point plain DNS at a resolver that forwards to AdminKit.

What does the /metadata response contain?

One object per device, rebuilt on every poll from the control plane’s device list and DNS events. Example output (illustrative, documentation domains):

{
  "generated_at": "2026-11-10T08:00:00.123456+00:00",
  "site_slug": "home",
  "devices": [
    {
      "device_id": "dev_01EXAMPLE0001",
      "name": "Living room camera",
      "scope_type": "device",
      "connections_24h": 42,
      "blocked_24h": 2,
      "last_seen": "2026-11-10T07:58:12+00:00",
      "last_blocked_qname": "c2.example.net"
    }
  ]
}
FieldMeaning
connections_24hDNS events attributed to the device in the trailing 24 hours, blocked or not.
blocked_24hThe subset of those events with action blocked.
last_seenTime of the device’s newest event the add-on received, inside or outside the window.
last_blocked_qnameThe domain of the latest blocked event in the window, or null.
nameThe device name from the control plane, or its ID if the device isn’t in the device list.

Only events scoped to a device count; site-wide events are skipped. A device with no events shows zeros and null. Until the first poll succeeds, /metadata returns an empty devices list and an empty generated_at.

Which Home Assistant sensors does it feed?

Three sensors, built from the core rest and template integrations — no HACS or custom component needed. Copy the add-on’s example sensor config into your configuration.yaml (or a packages file) and adjust the host/port. It adds:

  • sensor.adminkit_metadata — number of devices in the latest metadata snapshot, with the full device list as an attribute
  • sensor.adminkit_blocked_24h — total blocked queries across all devices in the last 24 hours
  • sensor.adminkit_dns_pointer — the DoH URL your router should be configured with

Two details need adjusting for current Home Assistant. The Supervisor registers each add-on in its internal DNS as the add-on ID with _ replaced by - (internal network), so a local adminkit_l1_dns add-on is reached as local-adminkit-l1-dns. And the old platform: template sensor format is no longer supported (template integration), so the blocked-count sensor goes under a top-level template: key:

sensor:
  - platform: rest
    name: AdminKit metadata
    resource: http://local-adminkit-l1-dns:8099/metadata
    method: GET
    scan_interval: 300
    value_template: "{{ value_json.devices | length }}"
    json_attributes:
      - generated_at
      - site_slug
      - devices

  - platform: rest
    name: AdminKit DNS pointer
    resource: http://local-adminkit-l1-dns:8099/dns-config
    method: GET
    scan_interval: 3600
    value_template: "{{ value_json.adminkit_l1_dns.doh_url }}"
    json_attributes:
      - adminkit_l1_dns

template:
  - sensor:
      - name: "AdminKit blocked queries (24h)"
        default_entity_id: sensor.adminkit_blocked_24h
        state: >-
          {{ state_attr('sensor.adminkit_metadata', 'devices')
             | map(attribute='blocked_24h') | sum }}

The RESTful sensor stores the devices array as an attribute, and the template sums blocked_24h across it. Match scan_interval on the metadata sensor to poll_interval_seconds; polling the add-on faster only re-reads the same snapshot.

What can you automate with these sensors?

Anything driven by the three sensor states or the devices attribute. A simple one raises a notification inside Home Assistant when blocked queries pass a threshold. Example (the threshold is illustrative; pick one from your own sensor history):

automation:
  - alias: "AdminKit: blocked queries above usual"
    triggers:
      - trigger: numeric_state
        entity_id: sensor.adminkit_blocked_24h
        above: 50
    actions:
      - action: persistent_notification.create
        data:
          title: "AdminKit Protective DNS"
          message: >-
            {{ states('sensor.adminkit_blocked_24h') }} queries blocked in the last 24 hours.

The numeric_state trigger fires when the value crosses the threshold, not on every update (automation triggers). A template over the devices attribute can name which device has the highest blocked_24h and its last_blocked_qname. The add-on has no per-query history, so an automation can’t show more than those fields.

What goes wrong, and how do you fix it?

Most problems show up in the add-on’s log tab or in the sensor state.

SymptomCauseFix
Add-on stops at once; log says api_key is requiredapi_key is emptyEnter the key from your engagement on the Configuration tab.
Options won’t savesite_slug has capitals or underscores, or the poll interval is outside 30-3600Use the slug exactly as Netbase gave it; keep the interval in range.
sensor.adminkit_metadata is 0, generated_at emptyNo poll has succeeded; log shows poll failedCheck api_url and api_key with Netbase.
Values freeze but don’t go unavailablePolls failing after earlier successes; the last snapshot keeps being servedRead the poll failed lines in the log.
Sensor unavailableWrong hostname or port in resourceUse local-adminkit-l1-dns:8099 or the host’s LAN IP.
{"error": "not found"}Path typo or query stringOnly exact /metadata and /dns-config are served.
Blocked-count sensor raises a repairOld platform: template formatMove it under template: as above.

Why metadata only, never raw query logs?

Because the add-on is built to keep as little as possible. AdminKit’s privacy commitments mean this add-on is deliberately limited to counts and a last-blocked-domain hint per device — never the DNS payload itself, never a raw per-query client IP, and never a full event log. The events it pulls do carry a client IP and each queried name; the add-on reads them only to count, then drops them. The snapshot lives in memory, and the add-on mounts no host folders, so nothing is written to disk and a restart starts empty.

One thing to be aware of: the local JSON API has no authentication. Anyone on your LAN who can reach port 8099 on the Home Assistant host can read device names and the last blocked domain. If that matters on your network, remove the host port mapping in the add-on’s Network settings and keep using the internal local-adminkit-l1-dns hostname from Home Assistant.

If you want a fuller picture of why that restraint matters for a home or small-office network, see our CGNAT guide for how shared addressing already complicates attributing traffic to one device, and is my router’s DNS hijacked? for what to check if you suspect your DNS settings were changed without your knowledge — a periodic resolver check remains the practical option on any network without a protective resolver in front of it.

Where does AdminKit fit?

This add-on is the Home Assistant half of AdminKit Protective DNS (L1) — a filtering resolver that blocks malware/C2 domains per device, deployed by changing your router’s DNS, which Netbase builds and runs for your network as a custom engagement. Talk to our team to scope one; the add-on then brings its per-device counts into your Home Assistant dashboard. See our home network solutions page for the free checks AdminKit offers a household.

This guide is general information, not a security audit of your specific network — see our disclaimer for what AdminKit's guidance does and does not commit to.

Frequently asked questions

Is this add-on in the Home Assistant add-on store?

No. Netbase provides the add-on's files as part of a Protective DNS engagement, and you install them as a local add-on (Settings → Add-ons → Add-on Store → local add-ons; current Home Assistant releases call add-ons "apps" and label this Settings → Apps → Install app → Local apps). Talk to our team at /contact/.

Does this add-on block DNS queries itself?

No — it is a client of AdminKit's control plane and the edge DoH service it configures against. It builds the DoH URL and polls device/event data for display; it does not re-implement DNS blocking.

How do I get a Protective DNS resolver to point my router at?

Through a Netbase Protective DNS engagement: Netbase sets up and runs the L1 filtering resolver and the control-plane API the add-on polls (GET /v1/dns/devices, GET /v1/dns/events) for your network, then gives you the control-plane URL and API key to configure (the add-on derives the DoH host from that URL). Talk to our team at /contact/ to scope it.

What does the add-on store about my devices?

Only aggregate metadata: a 24-hour connection count, a 24-hour blocked-query count, the last-seen timestamp and the most recently blocked domain, per device. It never stores or forwards raw client IPs, full DNS query logs, or DNS payload.

What if my router doesn't support DNS-over-HTTPS?

Point its plain-DNS setting at the fallback resolvers the add-on returns instead, or — if your router runs OpenWrt — use the OpenWrt package, which also attributes queries per device without needing router-level DoH support.

Want AdminKit to watch this for you?

Free checks tell you the state today. Protective DNS and monitoring tell you when it changes.

Huy Nguyen (David), Founder and CEO of Netbase JSC

Talk to an expert

Huy Nguyen (David), Founder & CEO, Netbase JSC

Ask whether this fix applies to your setup, or get a second pair of eyes on your DNS and mail records.