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