# proxmox-sdk

Schema-driven FastAPI SDK for the Proxmox API — generated, dual-mode, OpenAPI-first.

| Field |Value |
| --- | --- |
| Canonical URL | https://emersonfelipesp.com/proxmox-sdk |
| GitHub | https://github.com/emersonfelipesp/proxmox-sdk |
| Developer guide | https://emersonfelipesp.com/proxmox-sdk/developer |
| Roadmap | https://emersonfelipesp.com/proxmox-sdk/roadmap |
| Releases | https://emersonfelipesp.com/proxmox-sdk/releases |
| Stars | 3 |
| Forks | 0 |
| Latest release | v0.0.12 |

## Overview

proxmox-sdk is a FastAPI package that mirrors the Proxmox VE API as a fully typed OpenAPI surface, with 675 endpoints generated from Proxmox VE 9.2.

It runs in two modes out of the box: a mock mode (default) with auto-generated CRUD data so you can develop without a real cluster, and a real mode that proxies validated requests to a live Proxmox host.

v0.0.6 advances the schema to Proxmox VE 9.2 (9.1.11 retained), adds an automated weekly schema-update workflow that detects API drift and opens a PR, and hardens multi-version mock state isolation so parallel test runs on different schema versions never share in-memory state.

## Features

- 675 pre-generated Proxmox VE 9.2 endpoints with full OpenAPI schema (9.1.11 retained)
- Dual mode: mock (default) for development, real for production
- Automated weekly schema sync — detects upstream API drift and opens a PR automatically
- Multi-version CI matrix: latest, 9.2, and 9.1.11 each tested on every commit
- Per-version mock state isolation (PROXMOX_MOCK_STATE_NAMESPACE) — safe for parallel runs
- Per-service Docker tags: latest-pve, latest-pbs (Backup Server), latest-pdm (Datacenter Manager)
- Auto-generated mock data with in-memory CRUD operations
- Real API proxy with request/response validation
- Code generation: crawls the Proxmox API Viewer into OpenAPI
- FastAPI-generated Swagger UI at /docs
- Optional CLI / TUI extras with in-app view switching

## Stack

- Python
- FastAPI
- OpenAPI 3.0
- Pydantic

## Install

Primary command:

```shell
pip install proxmox-sdk
```

Then visit /docs on the running app for live OpenAPI / Swagger. For Docker, pull emersonfelipesp/proxmox-sdk:latest-{pve,pbs,pdm} per service surface.

## Links

| Label |URL |
| --- | --- |
| repo | https://github.com/emersonfelipesp/proxmox-sdk |
| docs | https://emersonfelipesp.com/proxmox-sdk/docs/ |