proxbox-api ~ FastAPI orchestrator for Proxbox

[ ~/proxbox-api ]tty0


   ___                _                       _    ___ ___
  | _ \_ _ _____ ___| |__  _____ __  ___    /_\  | _ \_ _|
  |  _/ '_/ _ \ \ /| '_ \/ _ \ \ /(_-<-_)  / _ \ |  _/| |
  |_| |_| \___/_\_\|_.__/\___/_\_\/__/__/ /_/ \_\|_|  |___|
   p r o x m o x  ⇄  n e t b o x   ·  f a s t a p i

emerson@netdevops:~/proxbox-api$ ./describe.sh proxbox-api

FastAPI orchestrator that bridges Proxmox VE and NetBox for the Proxbox suite.

proxbox-api is the FastAPI service that powers the Proxbox stack. It is the engine behind every Full Update click you see inside the netbox-proxbox NetBox plugin.

It exposes REST, Server-Sent Events and WebSocket endpoints so the plugin can discover, sync and stream live progress for clusters, nodes, VMs, containers, storage, snapshots and backups.

Internally it stands on two SDKs: netbox-sdk talks to the NetBox REST API as the write target, and proxmox-sdk talks to Proxmox VE as the read source. proxbox-api is the only place where both worlds are reconciled.

license=Apache-2.0python=3.11+netbox=4.5.x / 4.6.xproxmox=7.x / 8.xrelease=v0.0.10.post2

›overview

emerson@netdevops:~/proxbox-api$ cat OVERVIEW.md

proxbox-api is the FastAPI service that powers the Proxbox stack. It is the engine behind every Full Update click you see inside the netbox-proxbox NetBox plugin.

It exposes REST, Server-Sent Events and WebSocket endpoints so the plugin can discover, sync and stream live progress for clusters, nodes, VMs, containers, storage, snapshots and backups.

› stack

· Python 3.11+ / FastAPI 0.136 + uvicorn
· SQLModel 0.0.38 + aiosqlite
· Pydantic 2.13
· bcrypt + cryptography (Fernet)
· netbox-sdk 0.0.7.post6 (NetBox REST client)
· proxmox-sdk 0.0.3.post1 (Proxmox VE SDK)
· Next.js admin UI (nextjs-ui/)

›features

emerson@netdevops:~/proxbox-api$ ./features --list

├─FastAPI orchestrator with Swagger UI at /docs
├─REST + Server-Sent Events + WebSocket sync streams
├─Bcrypt-hashed API key auth (X-Proxbox-API-Key) with brute-force lockout
├─Encrypted credentials at rest (Fernet) — PROXBOX_ENCRYPTION_KEY required
├─SQLModel + SQLite for endpoint and key storage
├─Per-VM and per-endpoint sync flags driven by the netbox-proxbox plugin
├─Read-only Proxmox discovery — never mutates the source cluster
├─Bundled Next.js admin UI for endpoint configuration (nextjs-ui/)

›integrations

emerson@netdevops:~/proxbox-api$ ./integrations --map

# proxbox-api is the only place where the netbox-proxbox NetBox plugin, the netbox-sdk REST client and the proxmox-sdk Proxmox VE SDK meet.

// integration map — transports, auth & concurrency — hover any node for details

[netbox-proxboxNetBox plugin]HTTP REST · SSE · WebSocketauth: X-Proxbox-API-Key

write targetasync · cached GET 60s TTLPROXBOX_NETBOX_MAX_CONCURRENT

read sourceasync · mock | real · read-onlyPROXBOX_VM_SYNC_MAX_CONCURRENCY

[netbox-sdk0.0.7.post6]REST

[proxmox-sdk0.0.3.post1]REST

›

netbox-proxbox · NetBox plugin

[consumer (frontend)]

transport: HTTP / SSE / WebSocket
direction: netbox-proxbox → proxbox-api

netbox-proxbox is a Django plugin that lives inside NetBox and never talks to Proxmox itself. Every cluster, node and VM you see in NetBox got there because the plugin asked proxbox-api to fetch it.

The plugin stores three endpoint objects (Proxmox, NetBox, FastAPI) and dispatches sync requests to the FastAPI endpoint (this service). Progress comes back over Server-Sent Events and the live log viewer is fed by a WebSocket from proxbox-api.

· Triggers Full Update / per-VM / per-endpoint syncs over REST
· Streams progress to the plugin's UI via SSE (real-time bars)
· Pushes the proxbox-api log buffer back to the plugin via WebSocket
· Honours per-endpoint overwrite flags set in the plugin's UI
· Authenticates with the X-Proxbox-API-Key configured on the FastAPI endpoint object

→ view project [netbox-proxbox]

›

netbox-sdk · NetBox REST SDK

[downstream — write target]

transport: HTTP (NetBox REST API)
direction: proxbox-api → netbox-sdk → NetBox REST

netbox-sdk is the async Python toolkit for the NetBox REST API. proxbox-api uses it as the write side of every sync — clusters become NetBox cluster groups, nodes become devices, VMs become virtual machines, network interfaces and IP assignments are reconciled in place.

Reusing netbox-sdk means proxbox-api inherits its session pooling, typed responses, retry policy and concurrency knobs (PROXBOX_NETBOX_MAX_CONCURRENT, PROXBOX_NETBOX_GET_CACHE_TTL) without reinventing the HTTP layer.

· Pinned dependency: netbox-sdk 0.0.7.post6
· Single source of NetBox session creation in proxbox_api/session/
· Drives every DCIM, IPAM and Virtualization write the plugin asks for
· Cached GET layer (60s default) shared across the sync workflow
· Compatible with NetBox 4.5.x and 4.6.x — version detection lives here

→ view project [netbox-sdk]

›

proxmox-sdk · Proxmox VE SDK

[downstream — read source]

transport: HTTP (Proxmox VE REST API)
direction: proxbox-api → proxmox-sdk → Proxmox VE

proxmox-sdk is the schema-driven SDK that mirrors the Proxmox VE 8.1 API as 646 typed endpoints. proxbox-api uses it as the read side of every sync — clusters, nodes, storage, VMs, containers, snapshots and backups are all queried through it.

Because proxmox-sdk supports a mock mode out of the box, proxbox-api can be developed and tested end-to-end against a fake Proxmox cluster, with the same schema the production proxy validates. The proxmox-mock sub-package shipped under proxbox-api-repo at tag v0.0.7 is the integration-test counterpart.