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

What this add-on actually does

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 will 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.
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.

Before you start: what’s live and what isn’t

The add-on’s own code is complete and testable today — installing it, generating config, and serving /metadata and /dns-config all work locally. What is not deployed yet is the thing it talks to: AdminKit’s L1 Protective DNS resolver (the DoH host your router would actually query) and the control-plane API (api.adminkit.net, /v1/dns/*) it polls for device data. Until those ship, /dns-config and /metadata will build correctly but won’t have a live backend to resolve against or pull real device data from. Set this add-on up now if you want to be ready, not expecting a working filter yet.

Install (Home Assistant Supervisor)

This repository is not yet published as a Supervisor add-on store entry. To try it:

1. Copy the integrations/ha-addon folder from the AdminKit repository 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 table below).

Configuration options

Option	Type	Default	Description
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 /v1/dns/sites slug this add-on reports/configures for; must match a site you created via POST /v1/dns/sites.
poll_interval_seconds	int(30,3600)	300	How often to re-poll devices/events.
http_port	port	8099	Local port serving /metadata and /dns-config.

Pointing your network at AdminKit L1 DNS

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."
  }
}

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.

Home Assistant sensors

Home Assistant ships a rest sensor platform in core — no HACS or custom component needed. Copy homeassistant/sensors.yaml.example from the add-on folder into your configuration.yaml (or a packages file) and adjust the host/port. It adds:

• sensor.adminkit_devices — number of devices in the latest metadata snapshot
• 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

Why metadata only, never raw query logs

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. 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 until Protective DNS itself is live.

Where AdminKit fits

This add-on is one half of AdminKit’s planned Protective DNS product (L1) — a managed resolver that blocks malware/C2 domains per device, deployed by changing your router’s DNS. It is in early access and not live yet; this add-on lets you prepare the Home Assistant side of that setup ahead of time. See our home network solutions page for the fuller picture of what AdminKit offers a household today versus what’s still planned.