Technitium API

Technitium API

Use scripts/technitium.py (via uv run) to talk to the Technitium DNS server on dns-vm.lan (192.168.0.250:5380). The UI is at http://192.168.0.250:5380.

Credentials

Resolved in order: environment variable → keyring → error.

These are the same env var names the kenske/technitium Terraform provider reads, so any shell already wired up with infisical run -- ... from the /technitium/ path in Infisical will Just Work — no keyring setup needed.

First-time setup

NEVER run configure yourself — the user must enter the token directly so it does not appear in conversation logs.

If credentials are missing, ask the user to run this in their terminal (the ! prefix runs it in-session so the output lands here):

! uv run C:/Users/Blake/.claude/skills/technitium-api/scripts/technitium.py configure

See references/setup.md for how to mint a token before running configure.

Argument routing

Parse $ARGUMENTS. The first token selects the operation:

Append --json to any read operation for raw JSON.

If $ARGUMENTS is empty or unrecognized, show the table above and stop.

Execution

uv run C:/Users/Blake/.claude/skills/technitium-api/scripts/technitium.py $ARGUMENTS

Examples:

uv run .../technitium.py leases --sort ip
uv run .../technitium.py leases --scope HomeLan --json
uv run .../technitium.py zones
uv run .../technitium.py records lan
uv run .../technitium.py record add lan printer.lan A 192.168.0.42 --ttl 300
uv run .../technitium.py stats LastDay
uv run .../technitium.py top TopBlockedDomains LastDay --limit 20
uv run .../technitium.py logs --client 192.168.0.42 --per-page 100
uv run .../technitium.py resolve dns-vm.lan A

Output interpretation

• leases is the workhorse for "what's on my network?" — match hostnames to MAC vendor / IP. Devices with hostName: null are unidentified clients; the MAC prefix (first 3 octets) is an OUI you can look up. Reserved entries are intentional pins; dynamic are leased from the pool.
• zones and records lan: the lan zone is managed declaratively from homelab-services/services/dns/terraform-config/. If the user wants to add a permanent record, point them at the Terraform variable map (see the project_homelab_dns memory) instead of using record add here — record add is for one-off / debugging records that Terraform would otherwise drift on the next apply.
• stats and top: useful for "is the DNS server healthy?" and "what's generating the most traffic?".
• logs: requires the built-in "Query Logs (Sqlite)" app to be installed (it is, by default). If the call returns "app not found", the user has renamed or uninstalled it — pass --app and --class.
• Mutating ops (lease *, record *, cache flush, cache delete): Report success plainly. On error, surface the errorMessage from the API.

Gotchas

A new PUBLIC DNS record can look "broken" until Technitium's negative cache expires

Blake's workstation (and any LAN device) resolves through this server (192.168.0.250). When a brand-new public record is created (a fresh Cloudflare A/CNAME, an Azure custom-domain binding, etc.), Technitium may still be holding a cached NODATA / NXDOMAIN answer it fetched BEFORE the record existed, so the name fails locally even though it is live on the internet. The negative TTL is the authoritative zone's SOA minimum (Cloudflare = 1800s / 30 min), so it self-heals within ~30 min.

• Symptom: curl/browser says "could not resolve host" or returns the wrong/old answer on the LAN, but Resolve-DnsName <name> -Server 8.8.8.8 returns the correct record. The split between local resolver and 8.8.8.8 is the tell.
• Confirm it: cache list --domain <name> shows a record whose rData.dataType is DnsSpecialCacheRecordData with NegativeCache: ....
• Fix: cache delete <name> (surgical, preferred) or cache flush (nukes the whole resolver cache). Then resolve <name> A to verify a real answer returns. Tell the user other LAN devices clear on their own once the 30-min TTL lapses.

Exit codes

Reference files

• references/setup.md — how to mint a Technitium API token in the UI
• references/api-reference.md — endpoint cheatsheet + link to upstream APIDOCS.md

Related

• homelab-bootstrap skill — broader homelab gotchas
• infisical-cli skill — fetching /technitium/ secrets
• Memory: project_homelab_dns, feedback_technitium_provider_env_direct