Skip to content

Proxbox Backend Setup

The NetBox plugin requires a separate proxbox-api FastAPI service. The plugin stores configuration in NetBox, but sync requests are sent to this backend.

Backend Role

The current plugin code expects a configured FastAPIEndpoint object and uses it for:

  • device sync
  • virtual machine sync
  • full update
  • VM backup sync

Option 1: Install The Backend With pip

mkdir -p /opt/proxbox-api
cd /opt/proxbox-api
python3 -m venv venv
source venv/bin/activate
pip install proxbox-api==0.0.2.post3

Start it manually:

/opt/proxbox-api/venv/bin/uvicorn proxbox_api.main:app --host 0.0.0.0 --port 8800 --app-dir /opt/proxbox-api

Option 2: Run The Backend In Docker

docker pull emersonfelipesp/proxbox-api:latest
docker run -d --name proxbox-api -p 8800:8800 emersonfelipesp/proxbox-api:latest

Option 3: Run It As A systemd Service

This repository includes sample service files:

  • contrib/proxbox.service
  • contrib/proxbox-https.service

Install one of them:

sudo cp -v /opt/netbox/netbox/netbox-proxbox/contrib/proxbox.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now proxbox
sudo systemctl status proxbox

The sample unit expects the backend virtual environment under /opt/proxbox-api/venv and starts:

/opt/proxbox-api/venv/bin/uvicorn proxbox_api.main:app --host 0.0.0.0 --port 8800 --app-dir /opt/proxbox-api

Adjust the service file if your backend lives somewhere else.

TLS Notes

If you use the HTTPS sample unit and point it at NetBox-managed certificates, the backend process may need permission to read them:

sudo chmod +rx -R /etc/ssl/private/
sudo chmod +rx -R /etc/ssl/certs/

That is convenient, but you should review the security impact for your environment before using it.

Next Step In NetBox

After the backend is reachable, create these objects in the Proxbox UI:

  1. Proxmox API
  2. NetBox API
  3. ProxBox API (FastAPI)

Then return to Plugins > Proxbox and run Full Update.