jackson2w/claude-code-skills / home-assistant
home-assistant
UnverifiedThis skill should be used when configuring, troubleshooting, or extending a Home Assistant OS (HAOS) instance — installing add-ons/apps, editing configuration.yaml, setting up Tailscale/remote access, or troubleshooting onboarding, the Supervisor, or backups, or building automations/scripts/helpers/template switches/webhooks through HA's REST and websocket APIs. Trigger phrases include "Home Assistant add-on", "Home Assistant apps", "configuration.yaml", "HAOS", "Home Assistant Tailscale", "Supervisor", "HACS", "home assistant api", "create automation via api", "/api/config/automation/config", "input_boolean/create", "timer/create", "home assistant websocket", "template switch config flow", "webhook local_only", "ios shortcut webhook", "template value should be a string", "pause for 1 hour then revert".
Home Assistant OS (HAOS)
Operational notes for a Home Assistant OS appliance VM specifically (not a plain Home Assistant
Container/Docker install) — first built in this homelab 2026-07-13 as VMID 150 on Proxmox. For
the Proxmox/Terraform side of provisioning this kind of VM (UEFI, no cloud-init, appliance image
import), see the proxmox-terraform-provisioning skill instead — this skill covers the guest
OS/application layer once it's already running.
"Add-ons" is now "Apps"
Home Assistant renamed Settings → Add-ons to Settings → Apps in the 2026.2 release — purely cosmetic (still the same Supervisor-managed Docker containers underneath), done to reduce confusion between "Add-ons" and "Integrations" for new users. Any guide, screenshot, or memory referencing "Add-ons" on a current install means Apps. Individual app detail pages keep their existing tab names (Info / Log / Configuration / Documentation) — only the top-level menu label changed, not the per-app navigation.
Installing a non-default app
Not every app is in the default store. Community-maintained ones (e.g. the Tailscale app) need
their repository added first: Settings → Apps → ⋮ (store view) → Repositories → paste the
repo URL (e.g. https://github.com/hassio-addons/repository for the widely-used "Home Assistant
Community Add-ons" set). It then appears in the store under that repo, installs like any other app.
No normal shell, no cloud-init (guest agent: off until you enable it)
HAOS is a locked-down appliance OS, not a general Debian box:
- No SSH/root shell by default (advanced users can enable an SSH add-on, but treat this as intentionally locked down, not a bug).
- Ignores Proxmox cloud-init entirely — onboarding (creating the first admin account) happens through HA's own first-boot web wizard, not via injected SSH keys/config.
- The web UI's port is no longer reliably 8123. Confirmed on a fresh HAOS 18.2 build
(2026-08-22): the LAN-facing UI is served on port 80 by Supervisor's own proxy, while 8123
itself returns connection-refused from outside the guest (Core is presumably still bound to it
internally, just not exposed). Symptom if you assume 8123: ICMP ping succeeds, TCP to 8123 is
refused, but plain
http://<ip>(port 80) serves the real HA frontend fine — don't read the refused 8123 as the guest being down. Check both ports (nc -zv <ip> 80 8123) rather than assuming one. - HAOS ships qemu-guest-agent, but the VM needs
agent: 1(Terraformagent { enabled = true }). Corrected 2026-10-30: the "no working agent" note here was only ever true because the VM was built without that flag. Without it, HAOS ignores ACPI shutdown: everyqm shutdownand every pve shutdown waited the full 180 s and then SIGTERMed HA, a hard kill that risks its database. With it,qm shutdown 150took 25 s andqm agent 150 pinganswers (HAOS 18.4). The flag takes effect only after a full VM stop and start, not a guest reboot. Stop it cleanly from HA itself (Settings → System → power icon → Advanced → Shut down system), then apply. Without the agent, find the IP viaip neighon the Proxmox node, matched by MAC.
Editing configuration.yaml
Needs a text-editing app first — install one from the default store (no extra repo needed):
- File editor — simplest, opens directly into
/config,configuration.yamlis at the top level (created by default on first boot). - Studio Code Server — full VS Code in-browser if doing more than a one-line edit.
Always restart Home Assistant (Settings → System → Restart) after editing — changes to
configuration.yaml don't take effect live.
Tailscale access — add-on-based, not raw CLI
Because there's no normal shell, exposing HA over Tailscale goes through the Tailscale app
(hassio-addons/addon-tailscale, needs the community add-on repo above), not a hand-run
tailscale serve command the way every other Debian LXC/VM in this homelab is exposed:
- Install + start the Tailscale app, authenticate via the login URL shown in its Log tab. Originally noted as Chrome-only (other browsers reportedly misbehaving with this flow) — not reproduced on a 2026-08-22 build, where the same auth link worked fine in Safari. Try whatever browser is handy; only fall back to Chrome if the link actually misbehaves.
- In its Configuration tab, show "unused optional configuration options" to reveal:
share_homeassistant:disabled/serve/funnel— useservefor tailnet-only access (this homelab's standing default — see constraint #3 inhomelab/CLAUDE.md); only usefunnelif there's a genuine public-ingress need.share_on_port:443/8443/10000—443matches every other tailnet-only service in this homelab.
- Restart the Tailscale app itself (not just HA) after changing its config.
- Trusted proxies must be configured or HA rejects requests coming through the add-on's
reverse proxy with a plain
400: Bad Request(confirmed live 2026-08-22 — direct IP access still returned200the whole time, only the proxied path 400'd, which is the tell that this is what's wrong rather than HA actually being down). Two different mechanisms depending on version:- Older versions / still on YAML: add to
configuration.yamlvia the File Editor app, then restart HA:http: use_x_forwarded_for: true trusted_proxies: - 127.0.0.1 - Newer versions (confirmed on the 2026-08-22 HAOS 18.2 build): the
http:YAML key is silently ignored post-migration — editing it does nothing, no error, and HA shows a dedicated warning ("HTTP YAML configuration is ignored after migration ... stops working in 2027.2.0") the next time you open Settings if you still have a stale block in the file. Configure it via Settings → System → Network → HTTP server → Reverse proxy instead: toggle Trust X-Forwarded-For on, add each proxy IP under Trusted proxies (as a bare IP, e.g.127.0.0.1and192.168.50.181for a LAN Caddy instance — not a CIDR, despite the field's own hint text). Clicking Save on that card is the restart — no separate Settings → System → Restart needed. HA then shows a "Confirm new HTTP server configuration" dialog with a ~5-minute auto-revert countdown (a lockout safety net) — click Confirm once you've verified you can still reach it, or it silently reverts on its own. - If proxying through more than one hop (e.g. both a local Tailscale Serve add-on and a
separate Caddy host), list every hop's source IP in trusted proxies —
127.0.0.1alone covers the Tailscale/HAOS-local add-on, but a LAN reverse proxy on another host needs its own real IP added too.
- Older versions / still on YAML: add to
Mobile app setup
Two separate apps are needed, not one:
- Tailscale app — sign into the same tailnet, VPN toggle on. If HA "looks down" from a
phone, check this first — it's almost always the phone's own Tailscale connection status, not
the HA server (verify server health independently via
curlfrom a known-good host before assuming an outage). - Home Assistant companion app — server URL is the Tailscale hostname
(
https://<name>.<tailnet>.ts.net), not a LAN IP (LAN IP only works on home WiFi).
Backup/restore via Proxmox Backup Server
VM-level PBS backup/restore works the same as any other Proxmox VM (vzdump/qmrestore) with or
without the guest agent. Snapshot-mode backup completed cleanly before the agent was enabled
(2026-10-30); with it on, vzdump also gets an fs-freeze. One restore-test
gotcha: a qmrestore to a throwaway VMID preserves the original guest's MAC address — booting
it alongside the still-running original puts two VMs on the same LAN segment with an identical
MAC. Strip it first: qm set <throwaway-vmid> --net0 virtio,bridge=vmbr0 (omit the MAC) so
Proxmox generates a fresh one before starting the throwaway copy.
Building automations, scripts and helpers through the API (no UI clicking)
Proven 2026-10-31 and 2026-11-04 building the Proton VPN controls (Colorado toggle, per-device
1 h VPN-off switches) entirely from ansible-ctrl with a long-lived token. The UI is only needed
to make that token.
- Automations and scripts are plain REST.
GET|POST /api/config/automation/config/<id>and/api/config/script/config/<id>read and create/replace the whole config (the automation body carries its own"id"). It's live as soon as the POST returns, with no reload. Keep aGETcopy before replacing anything. - Nested templates are rejected. Writing
{{ … }}inside another{{ … }}fails with400 template value should be a string. Join the pieces with~inside a single template instead. - Helpers (
input_boolean,timer, …) can't be made over REST. Use the websocket API:{"type":"input_boolean/create","name":…},{"type":"timer/create","name":…,"duration":"01:00:00","restore":true},…/list. The entity_id is the slugified name. If no websocket library is installed, ~50 lines of stdlib Python does it: asockethandshake to/api/websocket, masked text frames,auth→auth_ok, then one command perid. - Template switches are config-flow helpers.
POST /api/config/config_entries/flow{"handler":"template"}→POST …/flow/<flow_id>{"next_step_id":"switch"}→POST …/flow/<flow_id>{"name","value_template","turn_on":[…],"turn_off":[…]}returnscreate_entry. To edit one later, use/api/config/config_entries/options/flowwith its entry_id. - Webhook triggers with
local_only: truereject requests that arrive through a reverse proxy or Tailscale Serve, because the source is a tailnet address. Call the LAN IP on port 80 (HAOS serves its UI there). Parse the body defensively:trigger.json if trigger.json is defined and trigger.json is mapping else {}. An Apple Shortcut "Get Contents of URL" set to POST with an empty JSON body arrives as{}, so a "no body = toggle" design works from both iOS and macOS Shortcuts. The HA iOS app's Shortcuts entity picker is unreliable (it offered only lights), so use a webhook. timer.startwith adurationoverride applies to that one run only. The next start without a duration uses the configured length again (verified). So you can drill a 1 h revert in 20 s without touching the helper.
Patterns that held up
- Switch between two outputs make-before-break. Turn the target on, wait, then turn the other
off, so the device is never on zero routes. Every run enables before it disables, which keeps
mode: restartsafe under rapid taps. - A template switch's state should reflect the intent, not raw entity state, when another actor
can also move that raw state. For example,
switch.iphone_vpn=input_boolean.iphone_vpn_pausedoff, not "a route is on", because a failover watcher may turn routes off. - A timed pause: a boolean holds the intent and a
timerwithrestore: truedoes the revert. A resume automation fires ontimer.finished, plus a backstop trigger (boolean on for duration + 2 min) and HA start with the boolean on and the timer idle. Resume clears the boolean last, after the route is back on. - Gate a safety-net automation with a condition, don't pause it. When an outside watcher also
pauses and resumes the same automation, two actors toggling its enabled state will eventually
undo each other. A
condition: state <pause boolean> offcan't race anything. - Use
mode: queuedfor short set/unset scripts whose runs must not interleave. - The UniFi integration sees route changes made outside HA about 10 s late (it polls). Its own
changes show instantly. Size any
for:guard with that lag in mind. - When a toggle "doesn't work", read the logbook first. A raw entity change shows no
script.<x> startedline, which means the user hit the wrong entity, not that the script failed.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |