Feature: Proxmox status & stats integration #5385

albinmedoc · 2025-06-05T20:59:52Z

Proposed change

This PR adds Proxmox VM and LXC container statistics support to Homepage, similar to the existing Docker and Kubernetes implementations. The feature allows users to monitor CPU usage, memory consumption, and VM/LXC status directly from their Homepage dashboard.

Key Features:

VM Statistics Widget: New proxmoxvm widget that displays CPU and memory usage for Proxmox VMs and LXC containers
Status Indicators: Visual status indicators showing running/stopped/paused states with appropriate color coding
Flexible Configuration: Support for both QEMU VMs and LXC containers via proxmoxType parameter
Service Integration: Seamless integration with existing service configuration structure

Implementation Details:

Created new API endpoint /api/proxmox/stats/[...service].js that fetches VM/LXC status from Proxmox API
Added ProxmoxStatus component for displaying VM status in service cards
Implemented ProxmoxVM widget component for detailed statistics display
Added comprehensive documentation with configuration examples
Follows existing patterns from Docker and Kubernetes implementations

Configuration Example:

- Plex:
  icon: plex.png
  href: "http://plex.home/"
  description: Media server
  proxmoxNode: pve
  proxmoxVMID: 100
  proxmoxType: qemu # Optional: defaults to qemu, can be lxc

Closes #1399

Type of change

New service widget
Bug fix (non-breaking change which fixes an issue)
New feature or enhancement (non-breaking change which adds functionality)
Documentation only
Other (please explain)

Checklist:

If applicable, I have added corresponding documentation changes.
If applicable, I have reviewed the feature / enhancement and / or service widget guidelines.
I have checked that all code style checks pass using pre-commit hooks and linting checks.
If applicable, I have tested my code for new features & regressions on both mobile & desktop devices, using the latest version of major browsers.

Files Changed:

src/widgets/proxmoxvm/component.jsx - New widget component for VM statistics
src/components/services/proxmox-status.jsx - Status indicator component
src/pages/api/proxmox/stats/[...service].js - API endpoint for fetching VM stats
src/components/services/item.jsx - Integration with service items
src/utils/config/proxmox.js - Proxmox configuration utilities (if applicable)
docs/configs/proxmox.md - Updated documentation with new features
src/skeleton/proxmox.yaml - Example configuration file

Testing:

Tested with both QEMU VMs and LXC containers
Verified CPU and memory statistics display correctly
Confirmed status indicators work for running/stopped/paused states
Validated configuration examples in documentation
Ensured responsive design works on both desktop and mobile devices

shamoon

Thanks for the PR. I see the use here but I need to think about whether we will accept this. I dont really have a way to test it, and as with k8s that has proven to be an issue. I think we can make this work. just need to think about it.

I have some other thoughts / questions about the design here:

Instead of proxmox_vmid / proxmox_vmid I think we should use the existing server / container. Perhaps just proxmox_vmid + container, which would let you differentiate docker vs proxmox.
Following from the above, does proxmox_type need to be set on every instance? Is that not a per-server thing?

Likely will have more, thanks again for your interest in contributing.

albinmedoc · 2025-06-06T05:59:04Z

2. Following from the above, does proxmox_type need to be set on every instance? Is that not a per-server thing?

You're absolutely right to ask about this! Looking at the image I've attached, you can see exactly why proxmox_type needs to be set per instance rather than per-server/node.
As shown in the Proxmox structure, a single node (like "pve" in the image) can host both LXC containers and VMs simultaneously:
LXC containers:

700 (plex)
1100 (adguard)
1200 (pterodactyl-panel)
1202 (pterodactyl-node2)

VMs:

100 (openmediavault)
300 (homeassistant)
400 (ollama)
600, 601, 602 (talos-ctl, talos-node1, talos-node2)
800 (gaming)

Since both LXC containers and VMs coexist on the same node with different VM IDs, the widget needs to know the specific type for each instance to make the correct API calls. The Proxmox API endpoints and data structures differ between LXC containers (/nodes/{node}/lxc/{vmid}/status) and VMs (/nodes/{node}/qemu/{vmid}/status).
This is why proxmox_type is required per instance configuration rather than being a node-level setting.

albinmedoc · 2025-06-06T06:04:25Z

as with k8s that has proven to be an issue

Do you have a issue/discussion for this?
I have no problems with kubernetes integration.

shamoon · 2025-06-06T06:29:57Z

I just meant that dealing with k8s issues that come up is challenging because I cant easily test.

Yea, I've been messing with getting a proxmox instance setup (on my Mac, yikes) and I understand why you chose to do it this way and about the _type parameter as well.

I've got a VM running, LXC giving me grief but should be enough to test this out

shamoon · 2025-06-06T06:48:26Z

So I managed to get a working setup:

In the end I got tripped up by needing to add permissions to the token for the /vms path. I dont see that documented anywhere?

shamoon

This seems pretty solid overall, nothing major here

docs/configs/proxmox.md

src/components/services/item.jsx

src/components/services/proxmox-status.jsx

src/pages/api/proxmox/stats/[...service].js

src/skeleton/proxmox.yaml

albinmedoc · 2025-06-06T07:00:11Z

I just used the same token I had created for the widget. There is documentation for that.

https://gethomepage.dev/widgets/services/proxmox/

Probably we want to move the instruction for creating a token to https://gethomepage.dev/configs/proxmox (the new page) and reference that from the widget docs.

shamoon · 2025-06-06T07:03:24Z

I just used the same token I had created for the widget. There is documentation for that.

https://gethomepage.dev/widgets/services/proxmox/

Probably we want to move the instruction for creating a token to https://gethomepage.dev/configs/proxmox (the new page) and reference that from the widget docs.

ah, gotcha. Yea I do think that'd make more sense

Co-authored-by: shamoon <[email protected]>

albinmedoc · 2025-06-06T07:38:43Z

I just used the same token I had created for the widget. There is documentation for that.
https://gethomepage.dev/widgets/services/proxmox/
Probably we want to move the instruction for creating a token to https://gethomepage.dev/configs/proxmox (the new page) and reference that from the widget docs.

ah, gotcha. Yea I do think that'd make more sense

Sounds great. I will implement that.

shamoon

Cool thanks

FriendlyNGeeks · 2025-06-07T21:20:40Z

I want to thank everyone involved on this PR.

albinmedoc · 2025-06-08T14:24:25Z

I want to thank everyone involved on this PR.

Thanks! I really love contributing to open source projects. I get more appreciation here than at my day job! 😄

dukeseb · 2025-06-10T23:45:24Z

Just for clarification how do you implement this? all im seeing here is how to add it to a widget but where do i define the node itself?

shamoon · 2025-06-10T23:50:55Z

The PR quite literally contains the relevant documentation, did you read it?

github-actions · 2025-07-11T03:34:43Z

This pull request has been automatically locked since there has not been any recent activity after it was closed. Please open a new discussion for related concerns. See our contributing guidelines for more details.

albinmedoc and others added 6 commits June 5, 2025 20:17

Add proxmoxVM statistics

aeded19

Add documentation

5cabad1

Remove debugging code

e387583

Fix lint errors

8c33aa0

Fix lint errors

030168f

Merge branch 'dev' into proxmox-stats

257d5b4

shamoon requested changes Jun 5, 2025

View reviewed changes

shamoon added 2 commits June 5, 2025 23:47

Merge branch 'dev' into proxmox-stats

16634e2

Add proxmox config to validation

7dfc17b

shamoon requested changes Jun 6, 2025

View reviewed changes

shamoon changed the title ~~Proxmox stats~~ Feature: Proxmox status & stats integration Jun 6, 2025

Apply suggestions from code review

2005c55

Co-authored-by: shamoon <[email protected]>

Apply suggestions from code review

fdb70a3

albinmedoc requested a review from shamoon June 6, 2025 09:41

shamoon enabled auto-merge (squash) June 6, 2025 13:52

shamoon approved these changes Jun 6, 2025

View reviewed changes

shamoon merged commit 5759596 into gethomepage:dev Jun 6, 2025
5 checks passed

github-actions bot locked as resolved and limited conversation to collaborators Jul 11, 2025

Uh oh!

Feature: Proxmox status & stats integration #5385

Feature: Proxmox status & stats integration #5385

Uh oh!

Conversation

albinmedoc commented Jun 5, 2025 • edited by shamoon Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Proposed change

Key Features:

Implementation Details:

Configuration Example:

Type of change

Checklist:

Files Changed:

Testing:

Uh oh!

shamoon left a comment

Choose a reason for hiding this comment

Uh oh!

albinmedoc commented Jun 6, 2025

Uh oh!

albinmedoc commented Jun 6, 2025

Uh oh!

shamoon commented Jun 6, 2025

Uh oh!

shamoon commented Jun 6, 2025

Uh oh!

shamoon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

albinmedoc commented Jun 6, 2025

Uh oh!

shamoon commented Jun 6, 2025

Uh oh!

albinmedoc commented Jun 6, 2025

Uh oh!

shamoon left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

FriendlyNGeeks commented Jun 7, 2025

Uh oh!

albinmedoc commented Jun 8, 2025

Uh oh!

dukeseb commented Jun 10, 2025

Uh oh!

shamoon commented Jun 10, 2025

Uh oh!

github-actions bot commented Jul 11, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

albinmedoc commented Jun 5, 2025 •

edited by shamoon

Loading