vault: session notes 2026-07-03

howto/proxmox-vm-setup-with-bells-and-whistles.md

@@ -0,0 +1,84 @@
+---
+type: howto
+title: "Setting Up a New VM on a Home Proxmox Server (with the Usual Bells and Whistles)"
+summary: Reusable runbook for spinning up a new VM on a home Proxmox host — scoped API token access, human-performed VM creation, pre-install snapshot, Tailscale-first access, off-host backup job, and shared host-facts documentation. Proven via the hermes01 build, reused for a Home Assistant OS VM.
+tags:
+  - type/howto
+  - tool/proxmox
+  - tool/tailscale
+  - convention/infra-safety-scoping
+  - domain/homelab
+scope: global
+last_updated: 2026-07-03
+update_note: experience-driven
+---
+
+# Setting Up a New VM on a Home Proxmox Server (with the Usual Bells and Whistles)
+
+This is the generalized pattern for standing up a new VM on a home Proxmox host with the
+access controls, safety net, and remote-access conventions that have proven out well.
+First proven end-to-end on the `hermes01` VM (self-hosted Hermes agent, completed
+2026-06-26); reused as the baseline for a second VM (Home Assistant OS) on 2026-07-03.
+It's a cross-project pattern, not tied to either specific service.
+
+This note is flagged `update_note: experience-driven` — when a new VM build finds a
+discrepancy (Proxmox UI changes, a step that no longer applies, a better ordering), update
+these steps rather than relying on a review date.
+
+## The steps
+
+1. **VM creation/import is a human-performed step, always.** Claude's Proxmox access should
+   be a scoped API token (e.g. `claude@pve!ops`, credentials in a local env file like
+   `~/.config/claude/pve.env`) allowlisted to specific VMIDs only — no host shell, and unable
+   to touch protected/unrelated VMs. Creating or importing a new VM, and expanding the
+   token's VMID allowlist to cover it, are both host-level changes that need a human at the
+   Proxmox UI/host shell, not something the agent executes directly.
+
+2. **Take a pre-install snapshot before installing the primary service.** Proxmox UI → VM →
+   Snapshots → Take Snapshot, right after the base OS is up and before the target
+   application/service goes on. This gives a one-click rollback point if the install goes
+   sideways — cheap insurance, always worth it.
+
+3. **Prefer Tailscale over public exposure for remote/admin access.** LAN SSH as a fallback
+   for local operations; never expose the VM or its services directly to the public internet.
+
+4. **Set up a recurring, off-host backup job — not just the local snapshot.** Datacenter →
+   Backup → Add:
+   - Weekly schedule is a reasonable default cadence.
+   - Snapshot mode (live, no VM downtime).
+   - ZSTD compression.
+   - Storage target should be off-host (e.g. a Synology NAS backup share) — an on-host-only
+     backup doesn't survive a host/disk failure.
+   - Retention: keep-last-4 (~a month of weekly restore points) is a reasonable default.
+   - **Select VMs individually per backup job — never blanket-select all VMs.** This keeps
+     protected/unrelated VMs from being accidentally swept into a job meant for one VM.
+
+5. **Verify the backup job actually works before trusting the schedule.** Run a one-off
+   manual "Run now" execution and confirm the backup lands on the target storage. Don't
+   assume the schedule will fire correctly untested.
+
+6. **Document host-level facts once, shared across all VM-specific projects — don't
+   duplicate them per project.** Host address, VMID inventory, the token-scoping convention,
+   and the safety rules (never touch protected VMs, no host shell, confirm destructive
+   actions) belong in one place that every VM-specific project imports/references. Per-project
+   duplication drifts — a safety rule updated in one project's docs silently goes stale in
+   another's. (Concretely: this was extracted from a single project's CLAUDE.md into a
+   shared host-layer CLAUDE.md referenced by both VM projects, once a second VM project
+   existed to justify it — don't extract shared docs speculatively before there's a second
+   real consumer.)
+
+7. **Before defaulting to a Docker/Container install for a self-hosted service, check
+   whether a native/appliance-OS install path exists.** Docker-only installs sometimes lack
+   the supervisor/plugin/add-on ecosystem that a purpose-built appliance OS provides (e.g.
+   Home Assistant OS vs. Home Assistant Container, which is Core-only with no add-on store).
+   If the appliance-OS path exists and the missing features matter, it's usually worth the
+   OS being non-negotiable (can't run "Ubuntu + the app" and get the same feature set) rather
+   than defaulting to whatever general-purpose OS you'd otherwise pick.
+
+## When this doesn't apply
+
+- Purely disposable/throwaway VMs (no data, no need to survive a host failure) can skip the
+  backup job (steps 4–5) — snapshot alone is enough.
+- If the Proxmox host itself is not yours to scope access to this tightly (e.g. shared
+  infra), the token-scoping convention in step 1 may not be available — fall back to
+  documenting who has host access instead.

journal/2026-07-03.md

@@ -128,3 +128,17 @@ tags: [scope/global, type/log]
 **Reason:** clear
 **Vault notes touched:**
 (none)
+
+## Session — 2026-07-03T17:21:48Z
+
+**Project:** /home/jared/dev/cc-os
+**Reason:** other
+**Vault notes touched:**
+(none)
+
+## Session — 2026-07-03T18:16:57Z
+
+**Project:** /home/jared/dev/cc-os
+**Reason:** prompt_input_exit
+**Vault notes touched:**
+(none)