Skip to content

Proxbox

Proxbox is a NetBox plugin that integrates Proxmox with NetBox through a separate FastAPI backend.

NetBox support tiers

netbox-proxbox declares two NetBox tiers, defined once in netbox_proxbox/compat.py and shared verbatim across the Proxbox plugin stack:

Tier NetBox range Behaviour
Stable 4.5.8 - 4.7.0 Admitted silently. Exercised in CI at v4.5.8, v4.5.10, v4.6.0, v4.6.6, and v4.7.0 GA.
Experimental NetBox 4.7.x pre-release builds within the declared loader range Loads for evaluation and warns via system check netbox_proxbox.W001; not a GA support promise.

GA support requires no setting, opt-in flag, or install step. NetBox 4.7.x pre-release builds within the declared loader range load for evaluation and emit an advisory warning; the notice is silenced with the silence_netbox_compatibility_warning key in the plugin's PLUGINS_CONFIG entry. Versions outside the declared support bands fail closed: NetBox warns, omits the plugin, and continues startup.

Compatibility

NetBox netbox-proxbox proxbox-api proxbox-api internal netbox-sdk (REST only) proxmox-sdk
4.5.8-4.7.0 GA v0.0.29.post1 v0.0.23.post3 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.29 v0.0.23.post3 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27 v0.0.23.post2 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc18 v0.0.23.post2 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc17 v0.0.23.post2 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc16 v0.0.23.post2 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc15 v0.0.23.post1 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc14 v0.0.23.post1 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc13 v0.0.23.post1 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc12 v0.0.23.post1 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc11 v0.0.23.post1 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc10 v0.0.23.post1 v0.0.13 v0.0.15
4.5.8-4.7.0 GA v0.0.27rc9 v0.0.22.post1 v0.0.13 v0.0.13
4.5.8-4.7.0 GA v0.0.27rc7 v0.0.22.post1 v0.0.13 v0.0.13
4.5.8-4.7.0 GA v0.0.27rc4 v0.0.22.post1 v0.0.13 v0.0.13
>=4.5.8 v0.0.23.post1 guest-VM-interface writer build / next release v0.0.10 v0.0.12
>=4.5.8 v0.0.23 guest-VM-interface writer build / next release v0.0.10 v0.0.12
>=4.5.8 v0.0.22 v0.0.19.post5 v0.0.10 v0.0.12
>=4.5.8 v0.0.21 v0.0.18.post5 v0.0.10 v0.0.12
>=4.5.8 v0.0.20.post3 v0.0.17.post1 v0.0.9.post1 v0.0.11.post1
>=4.5.8 v0.0.20.post2 v0.0.17.post1 v0.0.9.post1 v0.0.11.post1
>=4.5.8 v0.0.20.post1 v0.0.17.post1 v0.0.9.post1 v0.0.11.post1
>=4.5.8 v0.0.20 v0.0.17 v0.0.8.post1 v0.0.11
>=4.5.8 v0.0.19 v0.0.16 v0.0.8.post1 v0.0.9
>=4.5.8 v0.0.18.post1 v0.0.14 v0.0.8.post1 v0.0.3.post1
>=4.5.8 v0.0.18 v0.0.14 v0.0.8.post1 v0.0.3.post1
>=4.5.8 v0.0.17 v0.0.13 v0.0.8.post1 v0.0.3.post1
>=4.5.8 v0.0.16 v0.0.12 v0.0.8.post1 v0.0.3.post1
>=4.5.8 v0.0.15.post2 v0.0.11.post2 v0.0.8.post1 v0.0.5.post1
>=4.5.8 v0.0.15.post1 v0.0.11.post1 v0.0.8.post1 v0.0.3.post1
>=4.5.8 v0.0.15 v0.0.11 v0.0.8.post1 v0.0.3.post1
>=4.5.8 v0.0.14 v0.0.10.post2 v0.0.8.post1 v0.0.3.post1
>=4.5.8 v0.0.13.post4 v0.0.9.post2 v0.0.7.post6 v0.0.3.post1
>=4.6.0-beta2 v0.0.13.post2 v0.0.9.post1 v0.0.7.post6 v0.0.3.post1
>=4.6.0-beta2 v0.0.13.post1 v0.0.9 v0.0.7.post6 v0.0.3.post1
>=4.6.0-beta1 v0.0.12 v0.0.8.post1 v0.0.7.post6 v0.0.3.post1
>=4.5.7 v0.0.11 v0.0.7 v0.0.7.post4 v0.0.2.post2

proxbox-api is listed as the separately deployed backend service. It is not a Python dependency of netbox-proxbox; the plugin talks to it over REST, SSE, and WebSocket.

The current repository code declares support for:

  • NetBox 4.5.8 through 4.7.0, including official v4.7.0 GA
  • Plugin version 0.0.29.post1 in source

That support comes directly from the plugin config in this repository:

  • min_version = "4.5.8"
  • max_version = "4.7.0" (numeric ceiling for the certified GA tier)

This compatibility line is validated against NetBox v4.5.8 through v4.5.10 and v4.6.0 through v4.6.6 in the stable tier, plus official v4.7.0 GA at exact commit 5f06007e4c9bacc93ce17c1e645fc1143d60df3d. The source matrix verifies each checkout's commit and release metadata before installing its checksum-bound, artifact-hashed Python 3.12/Linux dependency lock. It includes per-endpoint API-only vs API+SSH access methods, tenant-scoped endpoint allowlists, bulk endpoint enablement, PDM endpoint sync, SDN inventory, Firecracker serializer hardening, dual VM interface sync, and the all-endpoint enabled=False no-connection guard.

The current source also provides a standalone Console tab on synchronized core virtual machines. NetBox performs VM and endpoint-object authorization; proxbox-api relays short-lived, origin-bound, one-use QEMU noVNC/terminal and LXC terminal sessions. The path does not navigate to or depend on another management UI. See Standalone Browser Console.

Current source pairing: netbox-proxbox 0.0.29.post1 <-> proxbox-api 0.0.23.post3 <-> proxmox-sdk 0.0.15 <-> netbox-sdk 0.0.13. This is the current sibling-source development stack, not a rewrite of historical release compatibility. This netbox-sdk version is proxbox-api's REST dependency only and does not provide the semantic MCP bridge.

Current backend-runtime pairing: netbox-proxbox 0.0.29.post1 <-> proxbox-api 0.0.23.post3 <-> proxmox-sdk 0.0.15 <-> netbox-sdk 0.0.13. This netbox-sdk version is proxbox-api's REST dependency only and does not provide the semantic MCP bridge.

The current released runtime pairing for this release line is proxbox-api 0.0.23.post2, proxmox-sdk 0.0.15, and netbox-sdk 0.0.13.

The 0.0.27rc4 release adds actionable VM console identity diagnostics and a permission-gated full synchronization repair action while retaining NetBox-native VM filtering, Proxmox metrics, the soft-deleted VM purge surface, and the official NetBox 4.7.0 GA compatibility contract. The historical rows remain documented below.

Important Packaging Note

The repository is ahead of the latest published PyPI release of netbox-proxbox.

  • Use the Git/source installation path if you want the code documented here.
  • Do not assume older prerelease installation instructions apply to the current branch.

What The Plugin Contains

The current codebase includes NetBox models for:

  • Proxmox endpoints (with per-endpoint sync overwrite flags and Settings tab)
  • NetBox endpoints (singleton)
  • FastAPI endpoints (singleton)
  • PBS endpoints (PBSEndpoint) and PDM endpoints (PDMEndpoint, PDMRemote) for companion plugin inventory
  • Proxmox clusters and hypervisor nodes (with links to NetBox Cluster and Device objects)
  • Proxmox storage rows and virtual-disk join table (ProxmoxStorageVirtualDisk)
  • Node SSH credentials (NodeSSHCredential) for SSH-based hardware discovery
  • Custom datacenter CPU models (ProxmoxDatacenterCpuModel)
  • VM templates (ProxmoxVMTemplate), cloud-init config (ProxmoxVMCloudInit), and cloud image templates (CloudImageTemplate)
  • Guest OS VM interfaces (GuestVMInterface) plus guest-interface address links (GuestVMInterfaceAddress) for dual Proxmox NIC and QEMU guest-agent interface modeling
  • Backup routines (Proxmox vzdump schedules with retention policies)
  • Replications (Proxmox storage replication metadata)
  • VM backups, VM snapshots, and VM task history
  • Proxmox VE firewall inventory: ProxmoxFirewallSecurityGroup, ProxmoxFirewallRule, ProxmoxFirewallIPSet, ProxmoxFirewallIPSetEntry, ProxmoxFirewallAlias, ProxmoxFirewallOptions (read-only, synced from proxbox-api)
  • SDN inventory (PVE 9.2+): controllers, zones, VNets, subnets, bindings, fabrics, route maps, and prefix lists
  • Firecracker Cloud inventory: FirecrackerHostPool, FirecrackerHost, FirecrackerImageTemplate, FirecrackerMicroVM
  • Operational models: ProxmoxApplyJob, DeletionRequest
  • Plugin-wide settings (ProxboxPluginSettings), including sync mode controls for VM, infrastructure, network, and SDN stages, the vm_interface_sync_strategy selector, plus interface-batch tunables

The plugin UI exposes sync actions for:

  • Devices (Proxmox node → NetBox Device)
  • Virtual machines and containers (with per-VM targeted sync)
  • Full update (single SSE stream covering devices, storage, VMs, virtual disks, backups, snapshots, network interfaces, IP addresses, VM interfaces, backup routines, and replications)
  • Storage
  • Virtual disks
  • Network interfaces and IP addresses
  • VM backups and snapshots
  • Backup routines
  • Replications

The plugin also provides a Backend Logs page for real-time log viewing from the proxbox-api backend.

Architecture

Proxbox is split into two services:

  1. The NetBox plugin from this repository.
  2. A separate FastAPI backend service, proxbox-api.

The NetBox plugin stores endpoint configuration and triggers sync requests. The backend talks to Proxmox and NetBox over HTTP and streams real-time progress updates via SSE (Server-Sent Events). Legacy WebSocket streaming is also supported.

For the current repository state, the recommended path is:

  1. Install the plugin from Git/source into the NetBox virtual environment.
  2. Run migrations and collect static assets.
  3. Install and run proxbox-api.
  4. Configure Proxmox API, NetBox API, and ProxBox API (FastAPI) objects in the NetBox UI.
  5. Run Full Update from Plugins > Proxbox.

See:

Read-Only Proxmox Behavior

Proxbox currently focuses on synchronization and discovery. The plugin does not directly manage Proxmox resources from NetBox.

Documentation Notes

  • The published docs site is generated with MkDocs and uses site-relative URLs such as /installation/2-installing-plugin-git/.
  • Generated CLI reference pages are rebuilt from the current proxbox_cli command tree.
  • Historical pages that describe older workflows are retained only when clearly labeled as legacy.

Stars History

Star History Chart