beszel-ipv6/pve-plan.md

Goal

Add Proxmox VE (PVE) stats for VMs and LXCs to Beszel, working similarly to how Docker containers are tracked: collect every minute, show stacked area graphs on the system page for CPU, mem, network, plus a dedicated global table/page showing all VMs/LXCs with current data.

Instructions

• Reuse container.Stats struct for PVE data transport and storage (compatible with existing averaging functions after minor refactor)

• Store clean VM name (without type) in container.Stats.Name; store Proxmox resource ID (e.g. "qemu/100") in container.Stats.Id field; store type ("qemu" or "lxc") in container.Stats.Image field — both Id and Image are json:"-" / CBOR-only so they don't pollute stored JSON stats

• Add PROXMOX_INSECURE_TLS env var (default true) for TLS verification control

• Filter to only running VMs/LXCs (check resource.Status == "running")

• pve_vms table row ID: use makeStableHashId(systemId, resourceId) — same FNV-32a hash used for systemd services, returns 8 hex chars

• VM type (qemu/lxc) stripped from name, shown as a separate badge column in the PVE table

• PVE page is global (shows VMs/LXCs across all systems, with a System column) — mirrors the containers page

• pve_stats collection structure is identical to container_stats (same fields: id, system, stats JSON, type select, created, updated)

• pve_vms collection needs: id (8-char hex), system (relation), name (text), type (text: "qemu"/"lxc"), cpu (number), memory (number), net (number), updated (number) Discoveries

• container.Stats struct has Id, Image, Status fields tagged json:"-" but transmitted via CBOR (keys 7, 8, 6 respectively) — perfect for carrying PVE-specific metadata without polluting stored JSON. Id is cbor key 7, Image is cbor key 8.

• makeStableHashId(...strings) already exists in internal/hub/systems/system.go using FNV-32a, returns 8-char hex — reuse this for pve_vms row IDs

• AverageContainerStats() in records.go hardcodes "container_stats" table name — needs to be refactored to accept a collectionName parameter to be reused for pve_stats

• deleteOldSystemStats() in records.go hardcodes [2]string{"system_stats", "container_stats"} — needs pve_stats added

• ContainerChart component reads chartData.containerData directly from the chartData prop — it cannot be reused for PVE without modification. For PVE charts, we need to either modify ContainerChart to accept a custom data prop, or create a PveChart wrapper that passes PVE-shaped chartData. The simplest approach: pass a modified chartData object with containerData replaced by pveData to a reused ContainerChart.

• useContainerChartConfigs(containerData) in hooks.ts is pure and can be called with any ChartData["containerData"]-shaped array — perfectly reusable for PVE.

• $containerFilter atom is in internal/site/src/lib/stores.ts — need to add $pveFilter atom similarly

• ChartData interface in types.d.ts needs a pveData field added alongside containerData

• The getStats() function in system.tsx is generic and reusable for fetching pve_stats

• go-proxmox v0.4.0 is already a direct dependency in go.mod

• Migration files are in internal/migrations/ — only 2 files exist currently; new migration should be named sequentially (e.g., 1_pve_collections.go)

• The ContainerChart component reads const { containerData } = chartData on line 37. The fix is to pass a synthetic chartData that has containerData replaced by pveData when rendering PVE charts.

• createContainerRecords() in system.go checks data.Containers[0].Id != "" before saving — PVE stats use .Id to store resource ID (e.g. "qemu/100"), so that check will work correctly for PVE too

• AverageContainerStats in records.go uses stat.Name as the key for sums map — PVE data stored with clean name (no type suffix) works correctly

• The containers table collection ID is "pbc_1864144027" — need unique IDs for new collections in the migration

• The container_stats collection ID is "juohu4jipgc13v7" — need unique IDs for pve_stats and pve_vms

• The containers table id field pattern is [a-f0-9]{6} min 6, max 12 — for pve_vms we want 8-char hex IDs: set pattern [a-f0-9]{8}, min 8, max 8

• In the migration file, use app.ImportCollectionsByMarshaledJSON with false for upsert (same as existing migration)

• CombinedData struct in system.go uses cbor keys 0-4 for existing fields — PVEStats should be cbor key 5

• For pve*stats in CreateLongerRecords(), need to add it to the collections array and handle it similarly to container_stats Accomplished Planning and file reading phase complete. No files have been written/modified yet. All relevant source files have been read and fully understood. The complete implementation plan is finalized. Ready to begin writing code. Files to CREATE

  File	Purpose
  internal/migrations/1_pve_collections.go	New pve_stats + pve_vms DB collections
  internal/site/src/components/routes/pve.tsx	Global PVE VMs/LXCs page route
  internal/site/src/components/pve-table/pve-table.tsx	PVE table component (mirrors containers-table)
  internal/site/src/components/pve-table/pve-table-columns.tsx	Table column defs (Name, System, Type badge, CPU, Mem, Net, Updated)

  Files to MODIFY

  File	Changes needed
  agent/pve.go	Refactor: clean name (no type suffix), store resourceId in .Id, type in .Image, filter running-only, add PROXMOX*INSECURE_TLS env var, change network tracking to use bytes
  agent/agent.go	Add pveManager *pveManager field to Agent struct; initialize in NewAgent(); call getPVEStats() in gatherStats(), store in data.PVEStats
  internal/entities/system/system.go	Add PVEStats []*container.Stats \json:"pve,omitempty" cbor:"5,keyasint,omitempty"` to CombinedData` struct
  internal/hub/systems/system.go	In createRecords(): if data.PVEStats non-empty, save pve_stats record + call new createPVEVMRecords() function
  internal/records/records.go	Refactor AverageContainerStats(db, records) → AverageContainerStats(db, records, collectionName); add pve_stats to CreateLongerRecords() and deleteOldSystemStats(); add deleteOldPVEVMRecords() called from DeleteOldRecords()
  internal/site/src/components/routes/system.tsx	Add pveData state + fetching (reuse getStats() for pve_stats); add usePVEChartConfigs; add 3 PVE ChartCard+ContainerChart blocks (CPU/Mem/Net) using synthetic chartData with pveData as containerData; add PVE filter bar; reset $pveFilter on unmount
  internal/site/src/components/router.tsx	Add pve: "/pve" route
  internal/site/src/components/navbar.tsx	Add PVE nav link (using ServerIcon or BoxesIcon) between Containers and SMART links
  internal/site/src/lib/stores.ts	Add export const $pveFilter = atom("")
  internal/site/src/types.d.ts	Add PveStatsRecord interface (same shape as ContainerStatsRecord); add PveVMRecord interface; add pveData to ChartData interface
  Key Implementation Notes
  agent/pve.go
  // Filter running only: skip if resource.Status != "running"
  // Store type without type in name: resourceStats.Name = resource.Name
  // Store resource ID: resourceStats.Id = resource.ID (e.g. "qemu/100")
  // Store type: resourceStats.Image = resource.Type (e.g. "qemu" or "lxc")
  // PROXMOX_INSECURE_TLS: default true, parse "false" to disable
  insecureTLS := true
  if val, exists := GetEnv("PROXMOX_INSECURE_TLS"); exists {
  insecureTLS = val != "false"
  }
  internal/hub/systems/system.go — createPVEVMRecords
  func createPVEVMRecords(app core.App, data []*container.Stats, systemId string) error {
  params := dbx.Params{"system": systemId, "updated": time.Now().UTC().UnixMilli()}
  valueStrings := make([]string, 0, len(data))
  for i, vm := range data {
  suffix := fmt.Sprintf("%d", i)
  valueStrings = append(valueStrings, fmt.Sprintf("({:id%[1]s}, {:system}, {:name%[1]s}, {:type%[1]s}, {:cpu%[1]s}, {:memory%[1]s}, {:net%[1]s}, {:updated})", suffix))
  params["id"+suffix] = makeStableHashId(systemId, vm.Id)
  params["name"+suffix] = vm.Name
  params["type"+suffix] = vm.Image // "qemu" or "lxc"
  params["cpu"+suffix] = vm.Cpu
  params["memory"+suffix] = vm.Mem
  netBytes := vm.Bandwidth[0] + vm.Bandwidth[1]
  if netBytes == 0 {
  netBytes = uint64((vm.NetworkSent + vm.NetworkRecv) * 1024 * 1024)
  }
  params["net"+suffix] = netBytes
  }
  queryString := fmt.Sprintf(
  "INSERT INTO pve*vms (id, system, name, type, cpu, memory, net, updated) VALUES %s ON CONFLICT(id) DO UPDATE SET system=excluded.system, name=excluded.name, type=excluded.type, cpu=excluded.cpu, memory=excluded.memory, net=excluded.net, updated=excluded.updated",
  strings.Join(valueStrings, ","),
  )
  *, err := app.DB().NewQuery(queryString).Bind(params).Execute()
  return err
  }
  system.tsx — PVE chart rendering pattern
  // Pass synthetic chartData to ContainerChart so it reads pveData as containerData
  const pveSyntheticChartData = useMemo(() => ({...chartData, containerData: pveData}), [chartData, pveData])
  // Then:

  records.go — AverageContainerStats refactor // Change signature to accept collectionName: func (rm \*RecordManager) AverageContainerStats(db dbx.Builder, records RecordIds, collectionName string) []container.Stats // Change hardcoded query string: db.NewQuery(fmt.Sprintf("SELECT stats FROM %s WHERE id = {:id}", collectionName)).Bind(queryParams).One(&statsRecord) // In CreateLongerRecords, update all callers: longerRecord.Set("stats", rm.AverageContainerStats(db, recordIds, collection.Name)) Relevant files / directories agent/pve.go # Main file to refactor agent/agent.go # Add pveManager field + initialization internal/entities/system/system.go # Add PVEStats to CombinedData internal/entities/container/container.go # container.Stats struct (reused for PVE) internal/hub/systems/system.go # Hub record creation (createRecords, makeStableHashId) internal/records/records.go # Longer records + deletion internal/migrations/0_collections_snapshot_0_18_0_dev_2.go # Reference for collection schema format internal/migrations/1_pve_collections.go # TO CREATE internal/site/src/ # Frontend root internal/site/src/types.d.ts # TypeScript types internal/site/src/lib/stores.ts # Nanostores atoms internal/site/src/components/router.tsx # Routes internal/site/src/components/navbar.tsx # Navigation internal/site/src/components/routes/system.tsx # System detail page (1074 lines) - add PVE charts internal/site/src/components/routes/containers.tsx # Reference for pve.tsx structure internal/site/src/components/routes/pve.tsx # TO CREATE internal/site/src/components/charts/container-chart.tsx # Reused for PVE charts (reads chartData.containerData) internal/site/src/components/charts/hooks.ts # useContainerChartConfigs (reused for PVE) internal/site/src/components/containers-table/containers-table.tsx # Reference for PVE table internal/site/src/components/containers-table/containers-table-columns.tsx # Reference for PVE columns internal/site/src/components/pve-table/ # TO CREATE (directory + 2 files)