Skip to content

jackson2w/claude-code-skills / home-assistant

home-assistant

Unverified

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

FileKindSize
SKILL.mdskill md12.8 KB
---
name: home-assistant
description: This 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`** (Terraform `agent { 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**: every `qm shutdown` and every pve
  shutdown waited the full 180 s and then SIGTERMed HA, a hard kill that risks its database. With
  it, `qm shutdown 150` took 25 s and `qm agent 150 ping` answers (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 via `ip neigh` on 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.yaml` is 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:

1. 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.
2. In its **Configuration** tab, show "unused optional configuration options" to reveal:
   - `share_homeassistant`: `disabled` / `serve` / `funnel` — use **`serve`** for tailnet-only
     access (this homelab's standing default — see constraint #3 in `homelab/CLAUDE.md`); only
     use `funnel` if there's a genuine public-ingress need.
   - `share_on_port`: `443` / `8443` / `10000` — `443` matches every other tailnet-only service
     in this homelab.
3. Restart the Tailscale app itself (not just HA) after changing its config.
4. **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 returned `200` the 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.yaml` via the File Editor app,
     then restart HA:
     ```yaml
     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.1` and `192.168.50.181` for 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.1` alone
     covers the Tailscale/HAOS-local add-on, but a LAN reverse proxy on another host needs its
     own real IP added too.

## Mobile app setup

Two separate apps are needed, not one:
1. **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 `curl` from a known-good host before
   assuming an outage).
2. **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 a `GET` copy
  before replacing anything.
- **Nested templates are rejected.** Writing `{{ … }}` inside another `{{ … }}` fails with `400
  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: a `socket` handshake to `/api/websocket`, masked text frames, `auth` →
  `auth_ok`, then one command per `id`.
- **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":[…]}` returns `create_entry`. To edit one later,
  use `/api/config/config_entries/options/flow` with its entry_id.
- **Webhook triggers with `local_only: true` reject 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.start` with a `duration` override 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: restart` safe 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_paused`
  off, not "a route is on", because a failover watcher may turn routes off.
- **A timed pause:** a boolean holds the intent and a `timer` with `restore: true` does the
  revert. A resume automation fires on `timer.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> off` can't race anything.
- Use `mode: queued` for 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> started` line, which means the user hit the wrong entity, not that the script failed.
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall