Proxbox

Proxbox is a NetBox plugin that synchronizes Proxmox infrastructure data into NetBox. It keeps your DCIM up-to-date with real Proxmox clusters, nodes, virtual machines, containers, backups, and Firecracker micro-VM inventory.

What It Does

Proxbox discovers and syncs the following from Proxmox into NetBox:

• Clusters and Nodes — Proxmox cluster name, mode (cluster/standalone), quorum status, node count, and Proxmox VE version. Each node includes online status, IP address, CPU usage, memory usage, and uptime at sync time. Optionally link to NetBox Cluster and Device objects.
• Virtual Machines — VM status, resources, and configuration
• Standalone browser console — a permission-gated Console tab on synchronized NetBox virtual machines, with QEMU noVNC/terminal and LXC terminal access relayed through proxbox-api without another management UI or browser-visible Proxmox credentials
• Containers (LXC) — Container details and settings
• Firecracker Cloud inventory — Host pools, host-agent VMs, image templates, and provisioned micro-VMs exposed separately from QEMU/LXC
• VM Snapshots — Point-in-time snapshots for recovery
• VM Backups — Backup jobs and restore points
• Storage — Datastores and storage content
• Network Interfaces and IPs — Proxmox NICs (net0, net1) as core NetBox VM interfaces, optional guest-OS interfaces (ens18, eth0) as plugin GuestVMInterface rows, and IP addresses assigned to VMs and containers
• Backup Routines — Backup job definitions from Proxmox
• Replications — Replication job status and configuration
• Data Protection Calendar — Month and ISO-week views for backups, snapshots, replications, and routines, with a combined permission-aware page and cluster, node, virtual-machine, date-range, and event-kind filters
• Opt-in service monitoring — Proxmox endpoint systemd service state collected through the optional netbox-rpc procedure os.linux.proxmox.show_systemctl_services

Note: All metrics (CPU, memory, uptime, etc.) are captured as point-in-time snapshots at sync time, not continuous monitoring.

Sync runs on-demand from the NetBox UI or scheduled automatically via NetBox's job system.

Backend API keys are adopted fail-closed without making the token field mandatory. The exact URL/IP, port, and TLS policy saved in the NetBox UI is 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, discovery is bounded to PLUGINS_CONFIG and same-site names derived from NetBox's trusted public origin; it never scans the network. An initialized backend whose key is not locally recoverable remains fail-closed and pending. Disabled endpoint rows make no network calls. Operators can still submit a key explicitly for manual rotation or recovery.

Additional Optional Plugins

Proxbox can be extended with standalone companion plugins. Install only the plugins you need; netbox-proxbox remains the base plugin and must be enabled before any companion plugin. The Ceph, PBS, and PDM inventory companions declare netbox-proxbox>=0.0.25.post2,<0.1.0; netbox-packer and netbox-rpc follow the same operational conventions without declaring that package floor. netbox-rpc is an operational companion: when it is installed, netbox-proxbox can run audited SSH procedures against Proxmox hosts (for example installing the proxbox-api cloud-image-build SSH key on a node, or collecting systemd service status for an endpoint) through the netbox-rpc engine instead of handling SSH itself. The integration is a soft dependency — see netbox_proxbox/integrations/rpc.py.

A companion package being present 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, respectively, is listed in PLUGINS; installed-but-disabled companions therefore remain inert. Once a companion is enabled, its imports are mandatory and startup fails if the installation is broken. Encryption recovery is the one fail-closed maintenance exception: netbox-pbs older than 0.0.1.post1 may start so its migrations can run, but recovery and key mutation remain blocked until its encrypted-field schema is upgraded.

Package	NetBox plugin	What it adds
netbox-pdm	netbox_pdm	Inventories Proxmox Datacenter Manager endpoints and the PVE/PBS remotes managed by PDM. It links PDM remotes back to Proxbox Proxmox endpoints and, when installed, netbox-pbs backup servers.
netbox-pbs	netbox_pbs	Synchronizes PBS directly, manages selected PBS configuration, and links backups to NetBox and Proxbox inventory; proxbox-api handles its Proxmox deployment and backup operations.
netbox-ceph	netbox_ceph	Adds read-only Ceph cluster inventory for Proxmox-managed Ceph: clusters, daemons, OSDs, pools, filesystems, CRUSH rules, flags, and health checks.
netbox-packer	netbox_packer	Tracks HashiCorp Packer image definitions and build execution records for Proxmox VM templates and image-factory workflows.
netbox-rpc	netbox_rpc	Audited SSH/RPC procedure engine. netbox-proxbox optionally uses it to install SSH keys on Proxmox hosts and to collect Proxmox endpoint systemd service status via netbox_proxbox.integrations.rpc.

This is the beginning of the README. Read the rest at the original. Read the full README ↗