server-proxmox-home-assistant-01/CLAUDE.md

Home Assistant on Proxmox — Claude Context

What This Repo Is

Ops/infra repo for installing and maintaining a Home Assistant OS (HAOS) VM on the home Proxmox server (pve). HAOS — not Home Assistant Container/Docker — was chosen deliberately: Container only runs HA Core (no Supervisor, no add-on store, manual updates), which is the exact feature gap this project exists to avoid. HAOS is an appliance OS; the VM's OS is Home Assistant, not Ubuntu-plus-a-service.

Shared Proxmox Context

Host-level facts (Proxmox host address, VM inventory, token scoping, backup/snapshot pattern) and the base safety rules live in the "Proxmox Host — Shared Infrastructure Context" section of ../CLAUDE.md (the umbrella file) — it auto-loads for any session in this directory, so read that first. (Note: @../ imports don't resolve across sibling directories in Claude Code, which is why this is inlined in the umbrella file rather than imported.)

HAOS-Specific Facts

Item	Value
VM OS	Home Assistant OS (HAOS) — appliance image, not a general Linux install
Install method	Official qcow2 disk image, imported on the Proxmox host (qm importdisk or equivalent) — human-in-the-loop step; the scoped API token has no host shell
VM access	No general SSH/apt admin surface — managed via the HA web UI and the HAOS console, unlike hermes01's systemd/apt setup
Status	Not yet created — VM import is a manual step performed by the human operator

Safety Rules (MUST follow)

Follow the shared host-level rules in the umbrella ../CLAUDE.md (never touch VM 100, no host shell, confirm destructive actions, scoped API token only). Additionally:

• VM creation/import for HAOS requires host-shell access the token doesn't have — treat as a human-performed step, never something Claude executes directly.
• Once the VMID is assigned, add it to the VM Inventory table in the umbrella ../CLAUDE.md.

Key Files

File	Purpose
(to be added as setup docs are written — e.g. a setup checklist mirroring proxmox-hermes/hermes-on-proxmox-setup-checklist.md)

Repo Conventions

• Documentation-first ops repo — no application code to build or test.
• Prefer editing existing files over creating new ones.
• Follow the same CLAUDE.md maintenance discipline as proxmox-hermes — see the maintenance guide referenced from the umbrella ../CLAUDE.md's Repo Conventions section (it resolves fine there since it's a subdirectory import, not a ../ cross-sibling one).

What Claude Should Do When Asked to Help

1. Read the umbrella ../CLAUDE.md's "Proxmox Host — Shared Infrastructure Context" section first for host facts and safety rules.
2. Confirm scope before executing anything against live infrastructure.
3. For HA-specific questions, reference: https://www.home-assistant.io/installation/
4. VM creation/import steps are the human's to run — describe the steps, don't attempt them.