$ path A — git / source into a NetBox venv (recommended)

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

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

   shellcopy

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

2. 02. Activate the NetBox virtualenv

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

   shellcopy

   source /opt/netbox/venv/bin/activate

3. 03. Install the plugin in editable mode

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

   shellcopy

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

4. 04. Enable the plugin in NetBox configuration

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

   configuration.pycopy

   PLUGINS = [
       "netbox_proxbox",
   ]

5. 05. Run database migrations

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

   shellcopy

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

6. 06. Collect static assets

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

   shellcopy

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

7. 07. Restart NetBox services

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

   shellcopy

   sudo systemctl restart netbox netbox-rq

8. 08. 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.

$ path B — netbox-docker

1. 01. Add the plugin to plugin_requirements.txt

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

   shellcopy

   echo 'netbox-proxbox' >> plugin_requirements.txt

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

   Mirrors the venv flow but inside the docker config directory.

   configuration/plugins.pycopy

   PLUGINS = [
       "netbox_proxbox",
   ]

3. 03. Rebuild and start NetBox

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

   shellcopy

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

4. 04. Run migrations inside the container

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

   shellcopy

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

5. 05. Verify

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

$ path C — proxbox-api backend (required)

1. 01. Pull the proxbox-api Docker image

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

   shellcopy

   docker pull emersonfelipesp/proxbox-api:latest

2. 02. 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.

   shellcopy

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

3. 03. Verify health

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

   shellcopy

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

$ endpoints — wire Proxmox, NetBox, and the FastAPI backend

1. 01. 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. 02. 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. 03. 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. 04. 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 & sync overwrite flags

1. 01. 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. 02. 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. 03. 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.