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
/metadataand/dns-configon port8099. - 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_keyandsite_slug, and read it from Home Assistant’s built-inrestandtemplatesensors. 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:
- Builds the AdminKit DoH URL for your configured site (
https://<dns host>/dns-query/site/<slug>) plus a plain-DNS fallback, and serves both atGET /dns-configon 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 typeapplication/dns-message, which RFC 8484 registered in IANA’s media type registry. - 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 atGET /metadata. - 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:
- Copy the add-on’s files to
/addons/adminkit_l1_dnson a Home Assistant OS/Supervised host — see Home Assistant’s own docs on testing local add-ons. - In Home Assistant, go to Settings → Add-ons → Add-on Store → local add-ons and install it from there.
- 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).
| Option | Type | Default | What it controls |
|---|---|---|---|
api_url | url | https://api.adminkit.net | AdminKit control-plane base URL. |
api_key | password | "" | AdminKit API key for your org — required. |
site_slug | match(...) | home | The site this add-on reports and configures for. |
poll_interval_seconds | int(30,3600) | 300 | How often to re-poll devices and events. |
http_port | port | 8099 | Local 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"
}
]
}
| Field | Meaning |
|---|---|
connections_24h | DNS events attributed to the device in the trailing 24 hours, blocked or not. |
blocked_24h | The subset of those events with action blocked. |
last_seen | Time of the device’s newest event the add-on received, inside or outside the window. |
last_blocked_qname | The domain of the latest blocked event in the window, or null. |
name | The 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 attributesensor.adminkit_blocked_24h— total blocked queries across all devices in the last 24 hourssensor.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.
| Symptom | Cause | Fix |
|---|---|---|
Add-on stops at once; log says api_key is required | api_key is empty | Enter the key from your engagement on the Configuration tab. |
| Options won’t save | site_slug has capitals or underscores, or the poll interval is outside 30-3600 | Use the slug exactly as Netbase gave it; keep the interval in range. |
sensor.adminkit_metadata is 0, generated_at empty | No poll has succeeded; log shows poll failed | Check api_url and api_key with Netbase. |
| Values freeze but don’t go unavailable | Polls failing after earlier successes; the last snapshot keeps being served | Read the poll failed lines in the log. |
| Sensor unavailable | Wrong hostname or port in resource | Use local-adminkit-l1-dns:8099 or the host’s LAN IP. |
{"error": "not found"} | Path typo or query string | Only exact /metadata and /dns-config are served. |
| Blocked-count sensor raises a repair | Old platform: template format | Move 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.
Sources
- Home Assistant — testing and debugging add-ons (local add-ons)
- Home Assistant — RESTful sensor integration
- RFC 8484 — DNS Queries over HTTPS (DoH), the standard the add-on's DoH URL implements
- Home Assistant Contributors — Your first app (local apps folder, installing from Local apps)
- Home Assistant Contributors — App options and schema types
- Home Assistant Contributors — App configuration reference (ports, startup, boot)
- Home Assistant Contributors — Talk to Home Assistant and the Supervisor (internal hostnames)
- Home Assistant — Template integration
- Home Assistant — Automation triggers
- Home Assistant — Common tasks for Home Assistant OS (apps, formerly add-ons)
- IANA — application/dns-message media type registration (RFC 8484)
- Cloudflare 1.1.1.1 docs — IP addresses
Related tools
Want AdminKit to watch this for you?
Free checks tell you the state today. Protective DNS and monitoring tell you when it changes.
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.