# 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 | 6 |
| Forks | 2 |
| Latest release | v0.0.13 |

## 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.

Beyond the server it ships a standalone async + sync Python SDK (ProxmoxSDK / SyncProxmoxSDK) with API-token and password/ticket authentication, a bring-your-own aiohttp session option, typed Ceph / PBS / PDM service clients, and an automated weekly schema-update workflow that detects upstream API drift and opens a PR.

## Features

- 675 pre-generated Proxmox VE 9.2 endpoints with full OpenAPI schema (9.1.11 retained)
- Standalone async + sync Python SDK (ProxmoxSDK / SyncProxmoxSDK) — no server required
- Dual mode: mock (default) for development, real for production
- Reliable password/ticket auth (API-prefixed ticket URL + unquoted PVEAuthCookie) plus API-token auth with TOTP
- Bring-your-own aiohttp session (session=) — reuse your connection pool, timeouts, tracing, or proxy
- Typed Ceph / PBS / PDM service clients on top of the transport backends
- Security hardening: SSRF-guarded download checksum discovery, credential redaction in logs, quoted SSH commands
- 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)
- 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/ |