Proxbox: NetBox plugin for syncing Proxmox VE inventory into NetBox

E

emersonfelipesp

New Member
May 18, 2026
1
3
3
Sao Paulo - Brazil
emersonfelipesp.com
Hello Proxmox community,

I’d like to share an open-source project I maintain: Proxbox, a NetBox plugin for synchronizing Proxmox VE infrastructure data into NetBox.

The goal is simple: keep NetBox updated with inventory data from real Proxmox environments, so Proxmox clusters, nodes, VMs, containers, storage, backups, snapshots, interfaces, and IP addresses can be reflected inside NetBox.


Current capabilities include:
  • Proxmox cluster and node inventory
  • VM and LXC container synchronization
  • Storage and virtual disk synchronization
  • Network interfaces and IP address discovery
  • VM backups and snapshots
  • Backup routines / vzdump schedules
  • Replication jobs
  • HA status visibility
  • VM task history
  • VM cloud-init data
  • Scheduled sync through NetBox background jobs
  • Real-time sync progress through SSE
  • Separate FastAPI backend: proxbox-api
  • Support for Proxmox VE 7.x, 8.x, and 9.x
  • Support for NetBox 4.5.x and 4.6.x
A few clarifications:
  • Proxbox is focused on inventory synchronization and discovery.
  • It does not try to replace the Proxmox VE UI.
  • Metrics such as CPU, memory, and uptime are captured as point-in-time data during sync, not as continuous monitoring.
  • For Proxmox VE 9, the API role needs VM.GuestAgent.Audit if you want VM IP discovery through the QEMU guest agent.
The project uses a separate backend service, proxbox-api, which talks to Proxmox and NetBox. The NetBox plugin stores the endpoint configuration and triggers sync jobs from the NetBox UI.

I’m sharing it here because Proxmox + NetBox is a common gap for people who want better infrastructure inventory, especially in environments where NetBox is already used as the source of truth for DCIM/IPAM.

Feedback, issues, and contributions are welcome.
 
  • Like
Reactions: gurubert, Johannes S and UdoB
Hello @emersonfelipesp. I'm trying to set up your plugin and have this:
Code: 
proxbox [2026-06-28 01:17:38,979] [WARNING] proxmox_core: Connected to Proxmox 1.2.3.4:8006 but cluster/status is forbidden; continuing in restricted mode
INFO:     10.42.1.248:38162 - "GET /proxmox/version?source=database&proxmox_endpoint_ids=2 HTTP/1.1" 200 OK

Is that expected? The role is the next:
Знімок екрана 2026-06-28 о 03.21.32.png
 
Ok, nevermind - fixed that.
I had to add the user to the group, assign the permissions especially for the group and for the token.
...complex Proxmox ACLs, huh!
 
Unfortunately after fixing the error with `cluster/status` the sync did not started to work. In 3 consoles (netbox, proxbox, netbox-worker) I do not see any traces, but the sync of nodes, VMs, etc fails. When I'm trying to check `Cluster Nodes` - see the error:

Code: 
[2026-06-28 01:57:00 +0000] ::ffff - "GET /login/ HTTP/1.1" 200 5.065
[2026-06-28 01:57:06 +0000] ::ffff - "GET /core/jobs/ HTTP/1.1" 200 316.980
[2026-06-28 01:57:10 +0000] ::ffff - "GET /login/ HTTP/1.1" 200 6.312
[2026-06-28 01:57:13 +0000] ::ffff - "GET /plugins/proxbox/ HTTP/1.1" 200 284.873
[2026-06-28 01:57:14 +0000] ::ffff - "GET /plugins/proxbox/keepalive-status/fastapi/1/ HTTP/1.1" 200 752.322
[2026-06-28 01:57:14 +0000] ::ffff - "GET /plugins/proxbox/keepalive-status/fastapi/1/ HTTP/1.1" 200 767.874
[2026-06-28 01:57:14 +0000] ::ffff - "GET /plugins/proxbox/keepalive-status/netbox/1/ HTTP/1.1" 200 1234.363
[2026-06-28 01:57:16 +0000] ::ffff - "GET /plugins/proxbox/keepalive-status/netbox/1/ HTTP/1.1" 200 1216.467
[2026-06-28 01:57:14 +0000] ::ffff - "GET /plugins/proxbox/keepalive-status/proxmox/1/ HTTP/1.1" 200 4848.903
[2026-06-28 01:57:14 +0000] ::ffff - "GET /plugins/proxbox/keepalive-status/proxmox/1/ HTTP/1.1" 200 4851.499
[2026-06-28 01:57:20 +0000] ::ffff - "GET /login/ HTTP/1.1" 200 4.730
[2026-06-28 01:57:19 +0000] ::ffff - "GET /plugins/proxbox/proxmox-card/1/ HTTP/1.1" 200 2078.642
[2026-06-28 01:57:25 +0000] ::ffff - "GET /plugins/proxbox/endpoints/fastapi/1/ HTTP/1.1" 200 150.898
[2026-06-28 01:57:25 +0000] ::ffff - "GET /plugins/proxbox/keepalive-status/fastapi/1/ HTTP/1.1" 200 730.726
[2026-06-28 01:57:25 +0000] ::ffff - "GET /plugins/proxbox/keepalive-status/fastapi/1/ HTTP/1.1" 200 756.846
[2026-06-28 01:57:30 +0000] ::ffff - "GET /login/ HTTP/1.1" 200 6.179
[2026-06-28 01:57:34 +0000] ::ffff - "GET /plugins/proxbox/endpoints/fastapi/1/openapi/ HTTP/1.1" 200 548.855
[2026-06-28 01:57:40 +0000] ::ffff - "GET /login/ HTTP/1.1" 200 5.596
[2026-06-28 01:57:43 +0000] ::ffff - "GET /plugins/proxbox/endpoints/fastapi/1/journal/ HTTP/1.1" 200 158.257
[2026-06-28 01:57:45 +0000] ::ffff - "GET /plugins/proxbox/endpoints/fastapi/1/changelog/ HTTP/1.1" 200 125.430
[2026-06-28 01:57:49 +0000] ::ffff - "GET /plugins/proxbox/clusters/ HTTP/1.1" 200 100.877
[2026-06-28 01:57:50 +0000] ::ffff - "GET /login/ HTTP/1.1" 200 5.760
[2026-06-28 01:57:51 +0000] ::ffff - "GET /plugins/proxbox/nodes/ HTTP/1.1" 200 102.402
[2026-06-28 01:57:58 +0000] ::ffff - "GET /plugins/proxbox/virtual_machines/ HTTP/1.1" 200 111.726
[2026-06-28 01:58:00 +0000] ::ffff - "GET /login/ HTTP/1.1" 200 4.886
[2026-06-28 01:58:08 +0000] ::ffff - "GET /plugins/proxbox/sync/schedule/ HTTP/1.1" 200 120.264
[2026-06-28 01:58:10 +0000] ::ffff - "GET /login/ HTTP/1.1" 200 5.567
[2026-06-28 01:58:20 +0000] ::ffff - "GET /login/ HTTP/1.1" 200 4.348

proxbox logs:

Code: 
proxbox [2026-06-28 01:56:16,436] [INFO] proxmox_core: Using IP x.x.x.x to authenticate with Proxmox
INFO:     10.42.0.160:56348 - "GET /proxmox/cluster/resources?type=vm&source=database&proxmox_endpoint_ids=2 HTTP/1.1" 502 Bad Gateway
INFO:     10.42.0.160:56358 - "GET /proxmox/endpoints HTTP/1.1" 200 OK
INFO:     10.42.0.160:56364 - "GET /health HTTP/1.1" 200 OK
INFO:     10.42.0.160:56372 - "GET /dcim/devices/create/stream?use_guest_agent_interface_name=true&fetch_max_concurrency=8&ignore_ipv6_link_local_addresses=true&primary_ip_preference=ipv4&parse_description_metadata=false&overwrite_device_role=true&overwrite_device_type=true&overwrite_device_tags=true&overwrite_device_status=true&overwrite_device_description=true&overwrite_device_custom_fields=true&overwrite_vm_role=true&overwrite_vm_type=true&overwrite_vm_tags=true&overwrite_vm_proxmox_tags=true&overwrite_vm_description=true&overwrite_vm_custom_fields=true&overwrite_vm_cloudinit=true&overwrite_cluster_tags=true&overwrite_cluster_description=true&overwrite_cluster_custom_fields=true&overwrite_node_interface_tags=true&overwrite_node_interface_custom_fields=true&overwrite_storage_tags=true&overwrite_vm_interface_tags=true&overwrite_vm_interface_custom_fields=true&overwrite_ip_status=true&overwrite_ip_tags=true&overwrite_ip_custom_fields=true&overwrite_ip_address_dns_name=true&sync_mode_vm=always&sync_mode_vm_template=always&sync_mode_vm_interface=always&sync_mode_mac=always&sync_mode_ip_address=always&sync_mode_cluster=always&sync_mode_node=always&sync_mode_storage=always&proxmox_endpoint_ids=2 HTTP/1.1" 400 Bad Request
INFO:     10.42.0.67:33578 - "GET /health HTTP/1.1" 200 OK
INFO:     10.42.0.67:33582 - "GET /health HTTP/1.1" 200 OK
INFO:     10.42.0.67:33586 - "GET /health HTTP/1.1" 200 OK
INFO:     10.42.0.67:45590 - "GET /health HTTP/1.1" 200 OK

Знімок екрана 2026-06-28 о 04.03.14.png
 

Attachments

  • Знімок екрана 2026-06-28 о 04.04.22.png
    Знімок екрана 2026-06-28 о 04.04.22.png
    131.5 KB · Views: 1
  • Знімок екрана 2026-06-28 о 04.04.28.png
    Знімок екрана 2026-06-28 о 04.04.28.png
    195.8 KB · Views: 2
Last edited:
I had upgraded the plugin to `netbox_proxbox: 0.0.21` and have the same error when come to Proxbox - Homepage, pick up proxmox endpoint and go to Cluster Nodes tab.
 
Tried to fix the token - no luck. In the netbox I did:
Code: 
ubuntu@netbox-7f4d9cb878-knt9k:/opt/netbox/netbox$ python manage.py proxbox_fix_tokens --fix
 loaded config '/etc/netbox/config/configuration.py'
 loaded config '/etc/netbox/config/extra.py'
 loaded config '/etc/netbox/config/logging.py'
 loaded config '/etc/netbox/config/plugins.py'
============================================================
FastAPIEndpoint Token Status
============================================================

FastAPIEndpoint ID: 2
  Name: ProxBox Endpoint
  Domain: proxbox-rsgeneral.netbox.svc
  IP Address: (none)
  Port: 8000
  Verify SSL: False
  Enabled: True
  Token: HAS TOKEN
  Token Preview: u4XalIurZNxyGk7Axa_v...
  Backend URL: http://proxbox-rsgeneral.netbox.svc:8000
  Backend Status: Has API keys configured
  Token Status: Unknown (HTTP 429)

============================================================
Some endpoints need attention. Run with --fix to attempt automatic registration.

Token fix completed.
ubuntu@netbox-7f4d9cb878-knt9k:/opt/netbox/netbox$ python manage.py proxbox_fix_tokens --fix
 loaded config '/etc/netbox/config/configuration.py'
 loaded config '/etc/netbox/config/extra.py'
 loaded config '/etc/netbox/config/logging.py'
 loaded config '/etc/netbox/config/plugins.py'
============================================================
FastAPIEndpoint Token Status
============================================================

FastAPIEndpoint ID: 2
  Name: ProxBox Endpoint
  Domain: proxbox-rsgeneral.netbox.svc
  IP Address: (none)
  Port: 8000
  Verify SSL: False
  Enabled: True
  Token: HAS TOKEN
  Token Preview: u4XalIurZNxyGk7Axa_v...
  Backend URL: http://proxbox-rsgeneral.netbox.svc:8000
  Backend Status: Has API keys configured
  Token Status: NOT registered with backend
  Attempting to register token...
  Registration: SUCCESS

============================================================
Some endpoints need attention. Run with --fix to attempt automatic registration.

Token fix completed.
ubuntu@netbox-7f4d9cb878-knt9k:/opt/netbox/netbox$

But the sync job still fails:
Code: 
{
    "proxbox_sync": {
        "params": {
            "batch_object_ids": [],
            "batch_object_type": null,
            "fastapi_endpoint_id": null,
            "netbox_branch_schema_id": null,
            "netbox_endpoint_ids": [],
            "netbox_vm_ids": [],
            "proxmox_endpoint_ids": [
                "1"
            ],
            "run_id": "0fba1793-71f8-4b21-91ae-e39fcfd9f8a4",
            "sync_types": [
                "devices"
            ]
        },
        "response": {
            "endpoint_runtimes": [
                {
                    "endpoint_id": 1,
                    "endpoint_name": "DEVHV01  Proxmox Endpoint",
                    "phases": [
                        {
                            "endpoint_id": 1,
                            "endpoint_name": "DEVHV01  Proxmox Endpoint",
                            "kind": "preflight",
                            "label": "Backend endpoint push",
                            "runtime_seconds": 0.536,
                            "status": "warning",
                            "summary": "Proxmox endpoint push failed: Failed to sync Proxmox endpoint to ProxBox backend: Invalid API key. 3 attempts remaining."
                        },
                        {
                            "endpoint_id": 1,
                            "endpoint_name": "DEVHV01  Proxmox Endpoint",
                            "kind": "cluster",
                            "label": "Cluster/node sync",
                            "runtime_seconds": 0.4,
                            "status": "warning",
                            "summary": "Failed to list Proxmox endpoints on ProxBox backend: Invalid API key. 2 attempts remaining."
                        },
                        {
                            "endpoint_id": 1,
                            "endpoint_name": "DEVHV01  Proxmox Endpoint",
                            "kind": "vm_template",
                            "label": "VM template sync",
                            "runtime_seconds": 0.028,
                            "status": "warning",
                            "summary": "Failed to list Proxmox endpoints on ProxBox backend: Too many failed authentication attempts. Please try again later."
                        },
                        {
                            "endpoint_id": 1,
                            "kind": "sse_stage",
                            "label": "endpoint-scope",
                            "runtime_seconds": 0.0,
                            "status": "warning",
                            "summary": "Backend SSE stage completed",
                            "sync_type": "endpoint-scope"
                        }
                    ],
                    "runtime_seconds": 0.964
                }
            ],
            "runtime_summary": {
                "endpoint_count": 1,
                "endpoint_runtime_seconds": 0.964,
                "other_runtime_seconds": 1.38,
                "runtime_seconds": 2.344
            },
            "stages": [
                {
                    "endpoint_id": "1",
                    "result_summary": {
                        "error": "Failed to list Proxmox endpoints on ProxBox backend: Too many failed authentication attempts. Please try again later.",
                        "ok": false
                    },
                    "runtime_seconds": 0.0,
                    "stream_path": null,
                    "sync_type": "endpoint-scope"
                }
            ]
        },
        "runtime_seconds": 2.344
    }
}
It shows the status as "green" completed though :)
 
The image is expected to be executed as root which is forbidden in our organization. So I had to attach the volume into `/data` and set up some extra variables:

Code: 
  - name: PROXBOX_BIND_HOST
    value: "0.0.0.0"
  - name: PORT
    value: "8000"
  - name: PROXBOX_LOG_LEVEL
    value: "INFO"
  - name: PROXBOX_NETBOX_GET_CACHE_TTL
    value: "120"
  - name: XDG_DATA_HOME
    value: "/data"
  - name: XDG_CONFIG_HOME
    value: "/data"
  - name: XDG_CACHE_HOME      # belt-and-suspenders for any lib that uses it
    value: "/data"
  - name: HOME                # so anything ignoring XDG still lands on the PVC
    value: "/data"

After setting that some sync tasks started to work (ok, I had also to fix the token because Netbox+Plugin could not communicate with Proxbox.)
Another problem is that the pod want to write something into `/var/log/proxbox.log` (why? Why we cannot write into stdout???). When You run with RO filesystem and non-root, you have to debug for a lot of issues.

...keep testing.
 
You must log in or register to reply here.
Top Bottom
Back