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

---
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 can actually see. Per-project
   duplication drifts — a safety rule updated in one project's docs silently goes stale in
   another's.

   **Where "one place" should live, if the VM projects are siblings under an umbrella
   directory**: put the shared facts directly in the umbrella's own CLAUDE.md, not in a
   separate sibling directory referenced via `@../shared/CLAUDE.md`. Claude Code's `@path`
   import resolver does not follow `../` references that escape a file's own directory
   tree — only same-directory and subdirectory imports resolve. A shared-facts file one
   level up and over from each VM project's CLAUDE.md silently never loads in a session
   scoped to that project; the path renders as a dead pointer. Verified empirically by
   launching a session with cwd inside a sibling project and checking which CLAUDE.md
   *content* (not just referenced paths) was actually present in context.

   The umbrella CLAUDE.md doesn't have this problem — it already auto-loads for any
   subdirectory cwd via Claude Code's ancestor-directory walk, so inlining the shared
   facts there makes them visible everywhere for free, no import needed. Per-project
   CLAUDE.md files then just point to it in prose ("see the umbrella CLAUDE.md's Proxmox
   Host section") rather than via `@import`. Subdirectory-descending imports (e.g. the
   umbrella file importing `@some-project/docs/foo.md`) are unaffected by this and work
   fine — the restriction is specifically on upward (`../`) traversal.

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.