58 lines
2.9 KiB
Markdown
58 lines
2.9 KiB
Markdown
# 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.
|