proxmox-sdk

Schema-driven FastAPI package for Proxmox API: OpenAPI generation, mock data, and in-memory CRUD operations.

📚 Full Documentation

Features

• Dual Mode: Mock mode (default) for development, Real mode for production Proxmox integration
• 675 Operations / 449 Endpoints: Pre-generated Proxmox VE 9.2 API with full OpenAPI schema
• Mock Data: Automatically generate mock data for all endpoints with in-memory CRUD
• Real API Proxy: Validated proxy to real Proxmox VE API with request/response validation
• Code Generation: Automatically crawl Proxmox API Viewer and convert to OpenAPI schema
• Multi-version Support: Select multiple Proxmox versions with latest mapped to official Proxmox API viewer
• Swagger Docs: FastAPI auto-generates OpenAPI documentation at /docs

Supported Proxmox Versions

Version	Status	Schema directory
9.2	Primary (CI-tested)	proxmox_sdk/generated/proxmox/9.2/
latest	Alias for 9.2 (CI-tested)	proxmox_sdk/generated/proxmox/latest/
9.1.11	Previous release (CI-tested)	proxmox_sdk/generated/proxmox/9.1.11/

All three schema directories ship in the package and CI exercises them in parallel via PROXMOX_MOCK_SCHEMA_VERSION=[latest, 9.2, 9.1.11]. Older releases (8.x, 7.x) may still work for endpoints whose shapes have not changed, but they are no longer in the CI matrix — regenerate locally with proxmox-sdk-codegen --version-tag <your-version> if you need them.

Installation

pip install proxmox-sdk

Quick Start

Mock Mode (Default)

# Install
pip install proxmox-sdk

# Start server
uvicorn proxmox_sdk.main:app --reload

# View Swagger docs
# Open http://localhost:8000/docs

SDK Direct Usage (No Server Required)

from proxmox_sdk.sdk import ProxmoxSDK

# Async with mock data
async with ProxmoxSDK.mock() as proxmox:
    nodes = await proxmox.nodes.get()

# Or sync (blocking)
with ProxmoxSDK.sync_mock() as proxmox:
    nodes = proxmox.nodes.get()

CLI TUI

# Install with CLI extras
pip install proxmox-sdk[cli]

# Production TUI
pbx tui

# Mock TUI
pbx tui mock

Real Mode (Connect to Proxmox)

# Configure credentials
export PROXMOX_API_MODE=real
export PROXMOX_URL=https://proxmox.example.com:8006
export PROXMOX_API_TOKEN=PVEAPIToken=user@realm!tokenid=uuid

# Start server
uvicorn proxmox_sdk.main:app --reload

See the Quick Start Guide for more details.

Documentation

• Home - Overview and features
• Installation - Installation options (pip, uv, Docker, source)
• Quick Start - 5-minute getting started guide
• SDK Mock Usage - Using the SDK with mock data (no server required)
• Mock API - Mock mode guide with custom data
• Real API - Real Proxmox integration guide
• API Reference - Endpoint documentation
• Development - Contributing guide
• IDE Support - VS Code, Pylance, and type-checking setup
• Architecture - How it works internally
• FAQ - Frequently asked questions

Environment Variables

Mock Mode

• PROXMOX_API_MODE - Set to "mock" (default) or "real"
• PROXMOX_MOCK_SCHEMA_VERSION - Version tag to use (default: "latest")
• PROXMOX_MOCK_DATA_PATH - Path to custom mock data file (default: "/etc/proxmox-sdk/mock-data.json")
• PROXMOX_MOCK_STORE - Mock state backend: "sqlite" (default), "shared-memory", or "dict"
• PROXMOX_MOCK_STATE_PATH - Optional SQLite mock-state database path

Real Mode

• PROXMOX_API_MODE - Set to "real" to enable Proxmox integration
• PROXMOX_URL - Proxmox server URL (e.g., "https://proxmox.example.com:8006")
• PROXMOX_API_TOKEN - API token (recommended, format: "PVEAPIToken=user@realm!tokenid=uuid")
• PROXMOX_USERNAME - Username (fallback, format: "user@realm")
• PROXMOX_PASSWORD - Password (fallback)
• PROXMOX_API_VERIFY_SSL - Verify SSL certificates (default: true)

Server

• HOST - Host to bind to (default: "0.0.0.0")
• PORT - Port to bind to (default: "8000")

Development

# Install dependencies
uv sync --extra test

# Run tests
pytest

# Run linting
ruff check .
ruff format --check .

# Run type checks
uv run ty check proxmox_sdk tests --output-format concise
uv run pyright proxmox_sdk

IDE Support

Open the repository in VS Code. When prompted, install the recommended extensions (ms-python.vscode-pylance, ms-python.python, charliermarsh.ruff). Pylance picks up types from the installed package automatically because proxmox_sdk ships a py.typed PEP 561 marker.

Type checking uses two gates: ty for fast project checks and pyright for Pylance-compatible diagnostics. Both run at typeCheckingMode = "basic":

uv run ty check proxmox_sdk tests --output-format concise
uv run pyright proxmox_sdk

Docker

All images are Alpine-based (smaller footprint), built from this repository with uv and uv.lock in a multi-stage Dockerfile. Three variants are published to Docker Hub:

Variant	Tags	Description
Raw (default)	latest, <version>	Pure uvicorn, HTTP only. Smallest image.
Nginx	latest-nginx, <version>-nginx	nginx terminates HTTPS via mkcert; proxies to uvicorn.
Granian	latest-granian, <version>-granian	Granian (Rust ASGI server) with native TLS via mkcert. No nginx.

Upgrade note: before v0.0.2, only runtime+mkcert images existed. From v0.0.2+, latest is the raw uvicorn image. Pull latest-nginx for HTTPS with nginx.

Raw image (default)

Plain uvicorn on HTTP — the simplest option for local dev or when you put your own proxy in front.

docker pull emersonfelipesp/proxmox-sdk:latest
docker run -d -p 8000:8000 --name proxmox-sdk emersonfelipesp/proxmox-sdk:latest

Build from source:

docker build -t proxmox-sdk:raw .
docker run -d -p 8000:8000 proxmox-sdk:raw

Nginx image (nginx + mkcert HTTPS + uvicorn)

nginx terminates HTTPS on PORT (default 8000) using certificates from mkcert and proxies to uvicorn on 127.0.0.1:8001. supervisord manages both processes.

docker pull emersonfelipesp/proxmox-sdk:latest-nginx
docker run -d -p 8443:8000 --name proxmox-sdk-nginx \
  emersonfelipesp/proxmox-sdk:latest-nginx

Build from source:

docker build --target nginx -t proxmox-sdk:nginx .
docker run -d -p 8443:8000 proxmox-sdk:nginx

Granian image (granian + mkcert HTTPS)

Granian is a Rust-based ASGI server with native HTTP/2, WebSocket, and TLS support. This variant eliminates nginx and supervisord — a single granian process handles everything.

docker pull emersonfelipesp/proxmox-sdk:latest-granian
docker run -d -p 8443:8000 --name proxmox-sdk-granian \
  emersonfelipesp/proxmox-sdk:latest-granian

Build from source:

docker build --target granian -t proxmox-sdk:granian .
docker run -d -p 8443:8000 proxmox-sdk:granian

mkcert environment variables (nginx and granian images)

Variable	Default	Description
PORT	8000	Port the server listens on
MKCERT_CERT_DIR	/certs	Directory where certs are stored
MKCERT_EXTRA_NAMES	—	Extra SANs (commas or spaces), e.g. proxmox-api.lan,10.0.0.5
CAROOT	—	Mount a volume here to persist the local CA across container restarts
APP_MODULE	proxmox_sdk.mock_main:app	ASGI app to run (change to proxmox_sdk.main:app for real mode)

docker run -d -p 8443:8000 --name proxmox-sdk-tls \
  -e MKCERT_EXTRA_NAMES='myhost.local,192.168.1.10' \
  -e APP_MODULE='proxmox_sdk.main:app' \
  emersonfelipesp/proxmox-sdk:latest-nginx

To run a shell instead of starting the server, pass a command (the entrypoint delegates to it):

docker run --rm emersonfelipesp/proxmox-sdk:latest-nginx sh

License

MIT