# netbox-proxbox syncs Proxmox inventory into NetBox as a plugin

> netbox-proxbox is a NetBox plugin that discovers and syncs Proxmox clusters, nodes, virtual machines, containers, backups and storage into NetBox, with a permission gated console tab and an allowlist based backend discovery model. It sits at version 0.0.29.post6 and is classified as alpha.

**emersonfelipesp/netbox-proxbox** — Netbox Plugin for integration between Proxmox and Netbox

- Repository: https://github.com/emersonfelipesp/netbox-proxbox
- Website: https://emersonfelipesp.com/netbox-proxbox
- Stars: 606 · Forks: 66
- Language: Python
- License: Apache-2.0
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/emersonfelipesp-netbox-proxbox

## Installing the plugin into a NetBox environment

netbox-proxbox is a NetBox plugin that synchronizes Proxmox infrastructure data into NetBox, with the stated goal of keeping a DCIM up to date with real Proxmox clusters, nodes, virtual machines, containers, backups and Firecracker micro-VM inventory. The audience is network and systems teams who already treat NetBox as the record of what exists in the datacenter and who currently maintain that record by hand from the Proxmox web interface. The installation path is a standard NetBox virtualenv install, with the plugin package added alongside NetBox itself, and the repository ships a `reinstall.sh` script, a `Dockerfile.oci` and a `requirements.txt` that pins the package manager the project expects.

```bash
uv>=0.11.15
```

The packaging metadata marks the plugin as Development Status 3, Alpha, targeting Python 3.12 and 3.13, and requiring Python 3.12 or newer.

```toml
requires-python = ">=3.12"
```

That alpha classification is the first thing to weigh, and the version number, currently 0.0.29.post6, says the same thing. It is a young integration built by a single named author, and the release history shows three consecutive builds within two days in October 2026, which is the rhythm of active iteration rather than of a settled tool.

## What a sync actually copies across

The discovery surface is broad. For clusters and nodes, the plugin pulls the cluster name, whether it runs in cluster or standalone mode, quorum status, node count and the Proxmox VE version, and per node it records online status, IP address, CPU usage, memory usage and uptime at sync time, with optional linking to NetBox Cluster and Device objects. Virtual machines sync their status, resources and configuration, and containers sync their details and settings. There is a separate section for Firecracker cloud inventory, exposing host pools, host agent VMs, image templates and provisioned micro-VMs apart from the QEMU and LXC objects. The plugin also syncs VM restore points, VM backups with their restore points, storage datastores and their content, backup job definitions, and replication job status and configuration. The network layer is the fiddliest part. Proxmox NICs such as `net0` and `net1` become core NetBox VM interfaces, while guest-OS interfaces such as `ens18` and `eth0` become rows of the plugin's own `GuestVMInterface` model, and IP addresses are attached to both virtual machines and containers.

## Metrics are point-in-time readings, not monitoring

The documentation puts a note in bold and it deserves attention: all metrics, meaning CPU, memory and uptime, are captured as point-in-time readings at sync time, not continuous monitoring. That single sentence changes what the plugin is. It is an inventory synchroniser with a one-off reading of utilisation attached, not a monitoring agent. A NetBox dashboard showing the CPU usage of a node is showing the value read during the last sync, which could be minutes or hours old depending on your schedule. The plugin reinforces this by adding service monitoring as an opt-in feature rather than a default: endpoint systemd service state is collected through the optional `netbox-rpc` procedure `os.linux.proxmox.show_systemctl_services`, and only when that companion package is installed and enabled. If you are looking for something to alert on, this is not that tool, and the data model will not support it.

## Discovery is bounded to one configured endpoint

The security model is the most distinctive part of the design and worth reading carefully before installation. Backend API keys are adopted fail-closed without making the token field mandatory. The exact URL or IP, port and TLS policy saved in the NetBox UI form the automatic-discovery allowlist: the plugin probes only that configured target, never follows redirects, reuses an encrypted key only after the target accepts it, and generates a key only for an empty backend's one-time bootstrap. With no endpoint row configured, discovery is bounded to `PLUGINS_CONFIG` and same-site names derived from NetBox's trusted public origin, and the plugin never scans the network. An initialized backend whose key is not locally recoverable stays fail-closed and pending, disabled endpoint rows make no network calls at all, and operators can still submit a key explicitly for manual rotation or recovery. In practice this means the plugin will not discover your Proxmox cluster for you, and the URL you type into the NetBox UI is the whole scope of what it will ever contact.

## A console tab without exposing Proxmox credentials

One feature goes beyond inventory. The plugin adds a standalone browser console to synchronized NetBox virtual machines, and it is permission gated. The access path is QEMU noVNC or terminal for virtual machines and LXC terminal access for containers, and the whole session is relayed through proxbox-api rather than through another management user interface. The wording matters: the documentation says this happens without another management UI and without browser-visible Proxmox credentials. So an operator browsing NetBox can reach a guest console without the Proxmox web interface being exposed and without handing out cluster credentials, and NetBox's own permission model governs who may do it. That is a genuinely useful pattern for teams that want to hand out VM access from the system that already holds the inventory, and it is the feature most likely to change how a team operates even if they never look at the CPU numbers.

## Companion plugins that stay inert until enabled

The plugin extends through separate companion packages, and the extension mechanism has a rule that catches people out: having a companion installed in the virtual environment does not enable its Django app. Proxbox registers branching signals and PDM URL overrides only when `netbox_branching` or `netbox_pdm` is listed in `PLUGINS`, so an installed but disabled companion stays inert. Once enabled, its imports become mandatory and startup fails if the installation is broken, with one exception: netbox-pbs older than `0.0.1.post1` may start so its migrations can run, but recovery and key mutation stay blocked until its encrypted-field schema is upgraded. The Ceph, PBS and PDM companions declare `netbox-proxbox>=0.0.25.post2,<0.1.0`, while `netbox-packer` and `netbox-rpc` follow the same operational conventions without that floor. The companions cover Proxmox Datacenter Manager and PBS remotes, Proxmox Backup Server inventory, read-only Ceph cluster inventory, HashiCorp Packer image definitions, and an audited SSH and RPC procedure engine.

## Template builds need two gates, not one

Cloud-Init template image creation through `netbox-packer` is treated as a separately authorized capability, and the layering is worth understanding because it shows how the project handles privilege. The selected `ProxmoxEndpoint` must be enabled with both `allow_writes=True` and the default-off `allow_packer_template_builds=True`, and the narrow flag grants only netbox-packer template builds. The Templates tab action stays disabled until both gates pass, and the narrow value is pushed to proxbox-api for enforcement at its final write boundary, but only when the endpoint is enabled and the broad write gate is open. Disabling the endpoint or either gate revokes the backend capability, and the endpoint detail page shows the explicit narrow assertion for audit. The save-time push runs only after the NetBox transaction commits, and it records the last backend-confirmed grant. Endpoint deletion stays blocked after an unsuccessful revocation until proxbox-api confirms the grant is false, and the two template-build REST actions also require `core.run_proxmox_action`, recheck all three endpoint gates before backend access, and translate the NetBox primary key into proxbox-api's independent endpoint ID.

## A data protection calendar and the gaps in the docs

On top of the inventory, the plugin offers a Data Protection Calendar with month and ISO-week views covering backups, snapshots, replications and routines, with a combined permission-aware page and filters for cluster, node, virtual machine, date range and event kind. That is a reporting surface over the synced records, which is the right shape for a DCIM plugin. What the documentation leaves open is more noticeable in a project of this size. There is no stated support policy, no compatibility matrix in the README, though a COMPATIBILITY.md file exists in the repository, and no documented upgrade procedure or rollback. The dependency pins are strict and explained, with security floors for `cryptography` above the range affected by GHSA-g6cj-pr64-35w5 and for `requests` at 2.33.0 or newer, a floor the metadata explains by the TLS policy bypass and two streaming denial-of-service fixes in 2.8.0, and `pydantic` held between 2.13.3 and 2.14.0. The licence is Apache 2.0, which is permissive for commercial use and carries the usual notice requirement. The last push was on 2026-10-22, with v0.0.29.post6 published on 2026-10-16.

## Conclusion

Adopt netbox-proxbox if you already run NetBox as the source of truth for IPAM and want Proxmox inventory to flow into it automatically, on demand or on a NetBox job schedule. Do not adopt it if you need live metrics, since every CPU, memory and uptime value is a point-in-time reading taken when the sync runs, or if you are not willing to configure a single explicit backend endpoint, because discovery never scans the network. Before you commit, read the endpoint configuration page, then confirm that the version you pin still supports your NetBox release.

## FAQ

### What does netbox-proxbox sync from Proxmox into NetBox?

It syncs clusters and nodes with their status, versions and resource values, virtual machines, LXC containers, Firecracker micro-VM inventory, VM restore points, VM backups and their restore points, storage, network interfaces and IP addresses, backup routines, replications, and a data protection calendar built over those records.

### Does netbox-proxbox monitor Proxmox continuously?

No. The documentation states that all metrics, including CPU, memory and uptime, are captured as point-in-time readings at sync time, not continuous monitoring. Service monitoring through `netbox-rpc` is an opt-in companion feature.

### How does netbox-proxbox discover the Proxmox backend?

The URL or IP, port and TLS policy saved in the NetBox UI form the allowlist. The plugin probes only that configured target, never follows redirects and never scans the network, and with no endpoint row configured discovery is bounded to `PLUGINS_CONFIG` and same-site names derived from NetBox's trusted public origin.

### What Python version does netbox-proxbox need?

The package metadata sets `requires-python = ">=3.12"` and the classifiers list Python 3.12 and 3.13. It is also classified as Development Status 3, Alpha.

## Sources

- [emersonfelipesp/netbox-proxbox on GitHub](https://github.com/emersonfelipesp/netbox-proxbox)
- [License: Apache-2.0](https://github.com/emersonfelipesp/netbox-proxbox/blob/main/LICENSE)
- [Project website](https://emersonfelipesp.com/netbox-proxbox)
- [README](https://github.com/emersonfelipesp/netbox-proxbox/blob/main/README.md)
- [Releases](https://github.com/emersonfelipesp/netbox-proxbox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/emersonfelipesp-netbox-proxbox