# netbox-proxbox

NetBox plugin that synchronizes Proxmox infrastructure into NetBox via a FastAPI backend.

| Field |Value |
| --- | --- |
| Canonical URL | https://emersonfelipesp.com/netbox-proxbox |
| GitHub | https://github.com/emersonfelipesp/netbox-proxbox |
| Developer guide | https://emersonfelipesp.com/netbox-proxbox/developer |
| Roadmap | https://emersonfelipesp.com/netbox-proxbox/roadmap |
| Releases | https://emersonfelipesp.com/netbox-proxbox/releases |
| Stars | 567 |
| Forks | 64 |
| Latest release | v0.0.21 |

## Overview

netbox-proxbox keeps your DCIM in sync with real Proxmox clusters by streaming clusters, nodes, VMs, containers, storage, snapshots and backups straight into NetBox.

It pairs a NetBox plugin (Django) with a dedicated FastAPI service called proxbox-api that does the heavy lifting and pushes progress live over Server-Sent Events.

## Features

- Automatic sync: clusters, nodes, VMs, containers, storage, snapshots, backups
- Real-time progress via Server-Sent Events (SSE) streaming
- Granular per-VM and per-endpoint sync flags
- Live backend log viewer pulled from proxbox-api
- Endpoint configuration via CSV / JSON / YAML import & export
- Read-only discovery — never mutates resources on Proxmox
- Network interface and IP assignment tracking inside NetBox

## Stack

- NetBox plugin (Django / Python 3.12+)
- proxbox-api (FastAPI backend)
- Server-Sent Events for streaming
- MkDocs Material for docs

## Install

Primary command:

```shell
pip install netbox-proxbox
```

Plus the proxbox-api backend (Docker image or standalone). See docs.

## Source install path

### 1. Clone the repository into NetBox's plugins directory



On the NetBox host, drop the plugin source next to NetBox itself.



```shell
cd /opt/netbox/netbox/
sudo git clone https://github.com/emersonfelipesp/netbox-proxbox.git
```

### 2. Activate the NetBox virtualenv



Every NetBox install ships its own venv — use it so the plugin links against NetBox's exact dependencies.



```shell
source /opt/netbox/venv/bin/activate
```

### 3. Install the plugin in editable mode



Editable install means future `git pull`s pick up new code without re-installing.



```shell
pip install -e /opt/netbox/netbox/netbox-proxbox
```

### 4. Enable the plugin in NetBox configuration



Edit `/opt/netbox/netbox/netbox/configuration.py` and append `"netbox_proxbox"` to the `PLUGINS` list.



```configuration.py
PLUGINS = [
    "netbox_proxbox",
]
```

### 5. Run database migrations



Creates the plugin's tables (endpoints, plugin settings, sync history).



```shell
python3 /opt/netbox/netbox/manage.py migrate netbox_proxbox
```

### 6. Collect static assets



Required so the plugin's CSS/JS are served by NetBox.



```shell
python3 /opt/netbox/netbox/manage.py collectstatic --no-input
```

### 7. Restart NetBox services



Picks up the new plugin and serves it under Plugins → Proxbox.



```shell
sudo systemctl restart netbox netbox-rq
```

### 8. Verify



Open the NetBox web UI, navigate to Plugins → Proxbox. The home page should load with three empty endpoint lists — that means installation is healthy.

## Docker install path

### 1. Add the plugin to plugin_requirements.txt



On netbox-community/netbox-docker, plugin requirements live alongside the compose file.



```shell
echo 'netbox-proxbox' >> plugin_requirements.txt
```

### 2. Enable the plugin in configuration/plugins.py



Mirrors the venv flow but inside the docker config directory.



```configuration/plugins.py
PLUGINS = [
    "netbox_proxbox",
]
```

### 3. Rebuild and start NetBox



The build pulls the plugin from PyPI into the image; up -d boots NetBox + workers.



```shell
docker compose build --no-cache netbox
docker compose up -d
```

### 4. Run migrations inside the container



Same `manage.py migrate` as venv install, but routed through the running container.



```shell
docker compose exec netbox /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py migrate netbox_proxbox
```

### 5. Verify



Browse to NetBox → Plugins → Proxbox. If the page renders, you are ready to add endpoints.

## Backend install path

### 1. Pull the proxbox-api Docker image



The backend is the FastAPI service that actually talks to Proxmox and pushes streaming progress to the plugin.



```shell
docker pull emersonfelipesp/proxbox-api:latest
```

### 2. Run the backend on port 8800



Map host 8800 → container 8000. The plugin will reach this URL via the FastAPI endpoint object you create next.



```shell
docker run -d \
  --name proxbox-api \
  -p 8800:8000 \
  --restart unless-stopped \
  emersonfelipesp/proxbox-api:latest
```

### 3. Verify health



A 200 OK from /health means the backend is up. Need TLS or a non-Docker install? See the upstream backend docs.



```shell
curl -sf http://localhost:8800/health && echo OK
```

## Endpoint configuration

### 1. Create the Proxmox API endpoint

- In NetBox, go to Plugins → Proxbox → Proxmox Endpoints → Add.
- Fill in the Proxmox host or VIP, port (usually 8006), and either user/password or an API token. Toggle TLS verification according to your environment.

### 2. Create the NetBox API endpoint

- Plugins → Proxbox → NetBox Endpoints → Add.
- Point this at the same NetBox you are configuring (yes, NetBox calls itself), with port 443 and a NetBox API token that has write permissions on DCIM/Virtualization.

### 3. Create the ProxBox API (FastAPI) endpoint

- Plugins → Proxbox → FastAPI Endpoints → Add.
- Hostname or IP of the proxbox-api service, port 8800 (or whatever you mapped). This is the bridge that performs the actual sync and streams progress back over SSE.

### 4. Run a Full Update

From Plugins → Proxbox home page, click "Full Update". The page streams live SSE progress as clusters, nodes, VMs, containers, storage, snapshots and backups appear in NetBox.

## Plugin settings

### 1. Tune plugin settings

- Plugins → Proxbox → Plugin Settings exposes a singleton settings object.
- Useful knobs: guest-agent interface naming, Proxmox fetch concurrency, IPv6 link-local filtering, NetBox concurrency + retry policy, bulk-batch sizing, VM sync parallelism.

### 2. Configure SSRF protection

Same settings page. Enable / disable SSRF protection, allow specific private IPs or CIDRs. Keep the default unless you intentionally point endpoints at link-local or private addresses.

### 3. Set sync overwrite flags

- Every `overwrite_*` flag is configurable globally on plugin settings or per-endpoint on the Settings tab of each Proxmox endpoint.
- Per-endpoint flags use a tri-state: Use plugin default / Always overwrite / Never overwrite. This lets you treat one cluster as authoritative while merging from another.

## Screenshots

### Plugin home & dashboard

- Plugin home — endpoint status cards and quick-sync actions. (Proxbox plugin home page inside NetBox) - https://emersonfelipesp.com/netbox-proxbox/screenshots/home.png
- Operational dashboard — cluster and node summaries at a glance. (Proxbox operational dashboard) - https://emersonfelipesp.com/netbox-proxbox/screenshots/dashboard.png

### Endpoint configuration

- Proxmox API endpoints — every cluster Proxbox can reach. (List of configured Proxmox API endpoints) - https://emersonfelipesp.com/netbox-proxbox/screenshots/proxmox-endpoints.png
- Proxmox endpoint detail — credentials, TLS, mode of access. (Single Proxmox endpoint detail page) - https://emersonfelipesp.com/netbox-proxbox/screenshots/proxmox-endpoint-detail.png
- Per-endpoint sync settings — tri-state overwrite flags. (Per-endpoint Proxmox sync settings) - https://emersonfelipesp.com/netbox-proxbox/screenshots/proxmox-endpoint-settings.png
- FastAPI endpoints — the proxbox-api backend Proxbox talks to. (List of FastAPI / proxbox-api endpoints) - https://emersonfelipesp.com/netbox-proxbox/screenshots/fastapi-endpoints.png
- FastAPI endpoint detail — host, port, TLS verify. (FastAPI endpoint detail) - https://emersonfelipesp.com/netbox-proxbox/screenshots/fastapi-endpoint-detail.png
- NetBox endpoints — the self-referential write target. (List of NetBox endpoints (self-referential)) - https://emersonfelipesp.com/netbox-proxbox/screenshots/netbox-endpoints.png
- NetBox endpoint detail — token & API base URL. (NetBox endpoint detail) - https://emersonfelipesp.com/netbox-proxbox/screenshots/netbox-endpoint-detail.png

### Clusters, nodes, storage

- Clusters — every Proxmox cluster surfaced in NetBox. (Proxmox clusters synchronized into NetBox) - https://emersonfelipesp.com/netbox-proxbox/screenshots/clusters.png
- Nodes — devices that make up each Proxmox cluster. (Proxmox nodes per cluster) - https://emersonfelipesp.com/netbox-proxbox/screenshots/nodes.png
- Storage — pools discovered from Proxmox. (Proxmox storage pools) - https://emersonfelipesp.com/netbox-proxbox/screenshots/storage.png
- Storage detail — type, capacity, content classes. (Single storage pool detail) - https://emersonfelipesp.com/netbox-proxbox/screenshots/storage-detail.png

### Virtual machines & LXC containers

- Virtual machines — full inventory across all clusters. (All Proxmox VMs synchronized into NetBox) - https://emersonfelipesp.com/netbox-proxbox/screenshots/virtual-machines.png
- VM detail — Proxmox config tab plus NetBox-native fields. (Single virtual machine detail page) - https://emersonfelipesp.com/netbox-proxbox/screenshots/virtual-machine-detail.png
- LXC containers — discovered alongside KVM guests. (LXC containers managed by Proxmox) - https://emersonfelipesp.com/netbox-proxbox/screenshots/lxc-containers.png
- Container detail — config, network, snapshots. (Single LXC container detail) - https://emersonfelipesp.com/netbox-proxbox/screenshots/lxc-container-detail.png

### Backups, snapshots, replications

- Backups — vzdump archives discovered on each storage. (VM backup jobs discovered from storage) - https://emersonfelipesp.com/netbox-proxbox/screenshots/backups.png
- Backup detail — guest, size, mode, timestamp. (Single backup detail) - https://emersonfelipesp.com/netbox-proxbox/screenshots/backup-detail.png
- Snapshots — across VMs and containers. (VM and container snapshots) - https://emersonfelipesp.com/netbox-proxbox/screenshots/snapshots.png
- Snapshot detail — parent, RAM, description. (Single snapshot detail) - https://emersonfelipesp.com/netbox-proxbox/screenshots/snapshot-detail.png
- Backup routines — vzdump schedules + targets. (Backup routine definitions) - https://emersonfelipesp.com/netbox-proxbox/screenshots/backup-routines.png
- Backup routine detail — selection, retention, mailto. (Single backup routine detail) - https://emersonfelipesp.com/netbox-proxbox/screenshots/backup-routine-detail.png
- Replications — Proxmox replication jobs & status. (Replication job status and config) - https://emersonfelipesp.com/netbox-proxbox/screenshots/replications.png

### Task history

- Task history — Proxmox jobs surfaced inside NetBox. (VM task history) - https://emersonfelipesp.com/netbox-proxbox/screenshots/task-history.png
- Task detail — status, log output, duration. (Individual task detail) - https://emersonfelipesp.com/netbox-proxbox/screenshots/task-history-detail.png

## Links

| Label |URL |
| --- | --- |
| repo | https://github.com/emersonfelipesp/netbox-proxbox |
| docs | https://emersonfelipesp.com/netbox-proxbox/docs/ |
| backendRepo | https://github.com/emersonfelipesp/proxbox-api |
| Proxmox Forum | https://forum.proxmox.com/threads/proxbox-netbox-plugin-for-syncing-proxmox-ve-inventory-into-netbox.183646/ |
| Reddit r/Proxmox | https://www.reddit.com/r/Proxmox/comments/1tglo8y/proxbox_netbox_plugin_for_syncing_proxmox_ve/ |
| Reddit r/Netbox | https://www.reddit.com/r/Netbox/comments/1tglnow/proxbox_netbox_plugin_for_syncing_proxmox_ve/ |