Home Assistant Add-ons by akentner

Home Assistant Add-ons with automated upstream monitoring and version bumping via GitHub Actions.

This repository hosts production add-ons for Home Assistant Supervisor. Each add-on ships with:

• A strict config.yaml schema validated by internal/validate-addon-config.py
• A build.yaml that pins the Docker base image and the add-on version
• A .upstream.yaml (where applicable) that points the auto-update workflow at the upstream project
• A Dockerfile that vendors runtime assets where possible (no CDN dependency at runtime)

Add-on documentation: https://developers.home-assistant.io/docs/add-ons

Add-ons

Markdown Renderer

Renders Markdown directories as Docsify SPAs through Home Assistant Ingress, with optional git-based sync.

Renders Markdown directories as Docsify SPAs through Home Assistant Ingress. Multiple namespaces are served as isolated SPAs under a single add-on, each with vendored Mermaid + Kroki renderer support. Optional per-namespace git_pull keeps content fresh from a remote without manual intervention.

Features:

• Multi-namespace Docsify serving through a single HA Ingress panel
• Vendored Docsify 4.13 + Mermaid 11 JS — no runtime CDN dependency
• Per-namespace optional git pull at startup and on a configurable background interval
• Mermaid diagrams render in fenced ```mermaid blocks; PlantUML (and other Kroki formats) in fenced code blocks route to the configured kroki_url (defaults to https://kroki.io)
• Invalid namespace names fail-fast at startup with a clear log message

Phone Logger

Phone logging and adapter integration for Home Assistant.

Flexible input → resolver → output adapter pipeline for Home Assistant. Drop-in replacement for the legacy Fritz!Box call monitor workflow, backed by an upstream project that this repository tracks via auto-update.

Features:

• Flexible configuration of input, resolver, and output adapters
• Strict, Home Assistant-compliant schema
• Data persistence via the add-on volume

Meridian Claude Max Proxy

Exposes a local Anthropic-compatible API on port 3456 backed by a Claude Max subscription.

Drop-in replacement for api.anthropic.com on your local network. Lets Home Assistant automations call Claude through the standard Anthropic SDK using a Claude Max subscription instead of per-token API keys.

Features:

• Local Anthropic-compatible API proxy backed by Claude Max
• Configurable port (default: 3456)
• Automatic upstream version tracking

Network Tools

Network diagnostics and ARP-based host detection for Home Assistant.

Layer-2 host detection via arping, plus nmap, dig, ping, and traceroute for manual diagnostics. Scans a configurable host list at a configurable interval and exposes results through a REST endpoint that integrates with Home Assistant via a REST sensor.

Features:

• ARP-based host detection with MAC verification and reachability tracking
• Configurable scan interval (default: 30s); configurable disconnect_threshold for flapping suppression
• host_network: true for full Layer-2 access (raw ARP packets)
• REST endpoint at /arping_scan.json consumable by the REST integration

CUPS Print Server

Share printers via CUPS with AirPrint/mDNS discovery that actually keeps working.

Shares printers via CUPS with a permanent fix for known Avahi mDNS reliability issues, not just a restart workaround. Ships with the reflector disabled by default (configurable via avahi_reflector), a fixed mDNS hostname, and IPv6 mDNS resolution disabled by default.

Features:

• AirPrint-compatible printer sharing via CUPS, multiple printers from a single options list
• Avahi mDNS reflector disabled by default — prevents the legacy-unicast slot-exhaustion bug
• Fixed, stable mDNS hostname independent of the container's transient hostname across restarts
• IPv6 mDNS resolution disabled by default

IaC Runner

Bearer-authenticated OpenTofu/Terraform runner for homelab IaC against R2/S3/local state backends.

A Go HTTP service on port 8125 (distinct from terraform-bridge's 8124) that clones a Git repo (e.g. homelab-infra), runs tofu plan/apply against Tailscale-reachable homelab servers, and persists state in Cloudflare R2 (default), any S3-compatible backend, or a local file. Manual REST trigger only (POST /v1/plan, POST /v1/apply → GET /v1/runs/{id}); concurrent applies on the same repo are serialized by an in-process mutex.

Features:

• Bearer-auth on 0.0.0.0:8125 with Tailscale-bind gate (bind_address: 0.0.0.0 always refused) — no hassio_api, no SUPERVISOR_TOKEN
• Three state backends (r2 default, s3, local) with use_lockfile = true for R2/S3 + file-based lock for local
• SHA-256 hashed bearer at /data/iac-runner-token (chmod 600, atomic rename) + 24h grace rotation
• homeassistant_api: true + mqtt:need service for the Phase 18 MQTT Discovery wiring (sensors + buttons)
• host_network: true for SSH to homelab servers via Tailscale IPs

LiteLLM

OpenAI-compatible API gateway with bundled PostgreSQL — virtual keys, spend tracking, and model routing for HA Conversation and homelab apps.

Bundles LiteLLM (OpenAI-compatible API gateway for 100+ LLM providers) and PostgreSQL (state store for virtual keys + spend logs + model definitions) in a single container. Persists a master key with one-time auto-gen log-on first-start (operator pastes the logged sk-… key into the add-on Configuration tab). Drop-in api_base for the standard openai_conversation: integration in HA Core.

Features:

• 100+ LLM providers (OpenAI, Anthropic, Google, Azure, Ollama, Bedrock) routable through one master_key
• Bundled PostgreSQL — no external database add-on needed
• HA Conversation integration via the add-on Configuration tab (master_key + provider keys set there)
• Direct LAN/Tailscale access on port 4000 + HA Ingress for Swagger UI
• Postgres tuning via SIGHUP-reload (shared_buffers, log_min_duration_statement)
• Daily auto-update tracking LiteLLM upstream via .upstream.yaml

Gatus

Automated status and uptime monitoring with a beautiful dashboard.

Wraps the upstream TwiN/gatus image with a Home Assistant-compliant schema. Tracks upstream releases daily and bumps the add-on version when a new release ships.

Features:

• Endpoint health monitoring with configurable HTTP/TCP/ICMP probes
• Configurable alert destinations (Slack, Discord, email, …)
• Themeable status page served as a Docsify-like SPA

HAOS Monitor

Diagnostic monitor that records kernel log and I/O stalls of HAOS hosts that hang without a trace.

Own code, no upstream project. Keeps an SSH session to each observed host, logs kernel messages and I/O pressure to /share/haos-monitor/ and exposes the state as status JSON (for Gatus) and as MQTT discovery entities.

Features:

• Multiple hosts per add-on, one rotated log file each
• problem sensor with the reasons as attributes (stale data, I/O pressure, in-flight I/O, D-state tasks)
• Remote side uses shell builtins only, so it keeps working while the data disk is stalled

Secrets Sync

Keeps /config/secrets.yaml in sync with Bitwarden and SOPS.

Own code, no upstream project. Pulls secrets from pluggable providers (Bitwarden via the bw CLI, SOPS/age) and writes secrets.yaml plus optional files atomically, with a status page and a health endpoint for Gatus.

Features:

• Bitwarden items mapped to legacy-style keys, secure notes as files
• Collision policy, shrink guard and verified atomic writes; the last good file is always kept
• No secret values in logs, state or API; credentials only via environment

ntfy

Self-hosted push notifications with an ingress admin GUI for users, ACLs and tokens.

Wraps the upstream ntfy server and ships an ingress-only admin GUI in the Home Assistant sidebar. Live users, ACLs and tokens stay in ntfy's auth.db; the add-on options only carry an additive baseline.

Features:

• Users, ACL rules (incl. everyone and wildcards), topic x user matrix and tokens managed in the GUI
• Baseline users from the options, compatible with the old "ntfy Server" add-on; origin markers show where an entry came from
• Backups of auth.db, guarded reset actions and a versioned state export (schema 1)
• Bridge network: reachable inside the HA network as 72a005f5-ntfy:8000, GUI only through ingress

Admin UI Blueprint

Blueprint and demo for ingress admin GUIs: shared browser lib, Python server skeleton and the rules behind them.

Our own code, no upstream project. The add-on serves a demo GUI with fake data behind Home Assistant ingress and is the source of the lib that other add-ons copy with make sync-admin-ui.

Features:

• Component gallery, token view in light and dark, German and English switcher, sample CRUD with error states
• Rules checklist with the test that enforces each rule, plus a live spike page for the HA theme and layout facts
• Ingress-only: the GUI port is never published

Authentik

Open-source Identity Provider — SSO, OAuth2/OIDC, LDAP, SAML, and more.

Self-hosted identity provider with a built-in user management UI, flow engine for MFA/enrollment/recovery, and support for every major authentication standard. Ships with bundled PostgreSQL and Valkey (Redis-compatible) — no external database add-ons required.

Features:

• SSO via OAuth2 / OIDC / SAML / LDAP / SCIM
• Built-in user management and group policies
• Flow engine for custom authentication logic (MFA, enrollment, recovery)
• Bundled PostgreSQL and Valkey — no external dependencies
• Automatic migrations on startup

Note: Authentik is not served via HA Ingress. Access via http://<ha-ip>:9000 and configure a reverse proxy with TLS for production use.

Coding Assistants

Terminal with Claude Code, OpenCode and GitHub Copilot CLI in herdr sessions — accessible via SSH and web terminal.

Pre-alpha developer add-on that bundles Claude Code, OpenCode and the GitHub Copilot CLI into a single container exposed via SSH and a web terminal, with sessions managed by herdr. Designed for Home Assistant OS / Supervised installations where installing these tools on the host is not practical.

Status: Pre-alpha — APIs and configuration may change without notice.

Repository Conventions

• Three-file versioning scheme — every add-on keeps config.yaml (with subpatch X.Y.Z-N), build.yaml (no subpatch, just X.Y.Z), and README badges (base vX.Y.Z) in sync. Use make update-version ADDON=foo VERSION=1.2.3 to bump; manual edits will fail the validate-versions.sh pre-commit hook. The script also creates and pushes the <addon>/v<version> git tag. Images are built by one workflow, build.yml (calling the reusable _build-template.yml once per add-on and arch leg), which fires on a push to main touching anything inside an add-on directory (paths: "*/**" minus the non-add-on directories) — so a change to run.sh, a *.py helper or a Go source file rebuilds the image, not just a manifest edit. Pushing the tag builds nothing. Without a pushed version bump the HA store sees the new version but the image at ghcr.io does not exist → 404. A pre-push hook reports, but does not block, a bumped version with no matching tag; add-ons on the LOCAL_BUILD_ADDONS allowlist in internal/check-version-tags.sh are skipped entirely — those are built locally by the Supervisor and never pulled from ghcr.io.
• Auto-update for upstream wrappers — add-ons that wrap an upstream project carry a .upstream.yaml and participate in the daily Auto Update GitHub Actions workflow. The workflow bumps build.yaml and config.yaml to the latest upstream release and adds the release notes to CHANGELOG.md.
• Vendored assets over CDNs — runtime JS/CSS (Docsify, Mermaid, etc.) is downloaded at image build time and shipped inside the container. No CDN requests at runtime — required for ingress isolation and air-gapped installs.

Development

Adding a New Add-on

1. Create the directory: mkdir my-addon
2. Add the required files: config.yaml, build.yaml, Dockerfile, run.sh, README.md
3. Add .upstream.yaml only if the add-on wraps an upstream project
4. Run make init once to install development tooling
5. Run make validate-addons to verify the new add-on schema
6. Update this README with the new add-on entry

Local Tooling

# One-time setup
make init

# Lint all files (pre-commit hooks)
make lint

# Validate add-on configs
make validate-addons

# Run every check
make check-all

# Bump an add-on's version (NEVER edit versions manually — also creates and pushes the <addon>/v<version> git tag)
make update-version ADDON=markdown-renderer VERSION=1.1.0-4

Auto-Update System

The repository includes an automated system that monitors upstream repositories for new releases and bumps the corresponding add-ons. See docs/AUTO_UPDATE_GUIDE.md for the full architecture and operational guide.

Code Quality

This repository uses automated linting enforced by pre-commit hooks and GitHub Actions:

• YAML — yamllint for configuration files
• Shell — shellcheck for run.sh and helper scripts
• Markdown — markdownlint-cli2 for *.md files
• GitHub Actions — actionlint for .github/workflows/*.yml
• Dockerfiles — hadolint for Dockerfile best practices
• Versioning — internal/validate-versions.sh enforces the three-file scheme

Documentation

• Auto-Update System Guide — architecture and operations for the daily update workflow
• Versioning & Release Workflow — three-file scheme rationale and make update-version
• Home Assistant Add-on Development — official documentation