{"id":48801165,"url":"https://github.com/emersonfelipesp/proxmox-sdk","last_synced_at":"2026-05-24T22:02:47.716Z","repository":{"id":349229527,"uuid":"1195361798","full_name":"emersonfelipesp/proxmox-sdk","owner":"emersonfelipesp","description":"Proxmox Async SDK","archived":false,"fork":false,"pushed_at":"2026-05-12T13:20:57.000Z","size":5536,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-12T15:26:56.242Z","etag":null,"topics":["api","fastapi","lib","openapi","proxmox","proxmox-api","pydantic","sdk","swagger"],"latest_commit_sha":null,"homepage":"https://emersonfelipesp.github.io/proxmox-sdk/","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/emersonfelipesp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/security.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":".github/AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-29T15:25:12.000Z","updated_at":"2026-05-12T13:32:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/emersonfelipesp/proxmox-sdk","commit_stats":null,"previous_names":["emersonfelipesp/proxmox-openapi","emersonfelipesp/proxmox-sdk"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/emersonfelipesp/proxmox-sdk","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fproxmox-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fproxmox-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fproxmox-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fproxmox-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/emersonfelipesp","download_url":"https://codeload.github.com/emersonfelipesp/proxmox-sdk/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/emersonfelipesp%2Fproxmox-sdk/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33045145,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-13T13:14:54.681Z","status":"online","status_checked_at":"2026-05-14T02:00:06.663Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","fastapi","lib","openapi","proxmox","proxmox-api","pydantic","sdk","swagger"],"created_at":"2026-04-14T03:01:03.694Z","updated_at":"2026-05-24T22:02:47.702Z","avatar_url":"https://github.com/emersonfelipesp.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# proxmox-sdk\n\nSchema-driven FastAPI package for Proxmox API: OpenAPI generation, mock data, and in-memory CRUD operations.\n\n**📚 [Full Documentation](https://emersonfelipesp.github.io/proxmox-sdk/)**\n\n## Features\n\n- **Dual Mode**: Mock mode (default) for development, Real mode for production Proxmox integration\n- **675 Operations / 449 Endpoints**: Pre-generated Proxmox VE 9.2 API with full OpenAPI schema\n- **Mock Data**: Automatically generate mock data for all endpoints with in-memory CRUD\n- **Real API Proxy**: Validated proxy to real Proxmox VE API with request/response validation\n- **Code Generation**: Automatically crawl Proxmox API Viewer and convert to OpenAPI schema\n- **Multi-version Support**: Select multiple Proxmox versions with `latest` mapped to official Proxmox API viewer\n- **Swagger Docs**: FastAPI auto-generates OpenAPI documentation at `/docs`\n\n## Supported Proxmox Versions\n\n| Version | Status | Schema directory |\n|---|---|---|\n| 9.2 | Primary (CI-tested) | `proxmox_sdk/generated/proxmox/9.2/` |\n| latest | Alias for 9.2 (CI-tested) | `proxmox_sdk/generated/proxmox/latest/` |\n| 9.1.11 | Previous release (CI-tested) | `proxmox_sdk/generated/proxmox/9.1.11/` |\n\nAll three schema directories ship in the package and CI exercises them\nin parallel via `PROXMOX_MOCK_SCHEMA_VERSION=[latest, 9.2, 9.1.11]`. Older releases\n(8.x, 7.x) may still work for endpoints whose shapes have not changed, but they\nare no longer in the CI matrix — regenerate locally with\n`proxmox-sdk-codegen --version-tag \u003cyour-version\u003e` if you need them.\n\n## Installation\n\n```bash\npip install proxmox-sdk\n```\n\n## Quick Start\n\n### Mock Mode (Default)\n\n```bash\n# Install\npip install proxmox-sdk\n\n# Start server\nuvicorn proxmox_sdk.main:app --reload\n\n# View Swagger docs\n# Open http://localhost:8000/docs\n```\n\n### SDK Direct Usage (No Server Required)\n\n```python\nfrom proxmox_sdk.sdk import ProxmoxSDK\n\n# Async with mock data\nasync with ProxmoxSDK.mock() as proxmox:\n    nodes = await proxmox.nodes.get()\n\n# Or sync (blocking)\nwith ProxmoxSDK.sync_mock() as proxmox:\n    nodes = proxmox.nodes.get()\n```\n\n### CLI TUI\n\n```bash\n# Install with CLI extras\npip install proxmox-sdk[cli]\n\n# Production TUI\npbx tui\n\n# Mock TUI\npbx tui mock\n```\n\n### Real Mode (Connect to Proxmox)\n\n```bash\n# Configure credentials\nexport PROXMOX_API_MODE=real\nexport PROXMOX_URL=https://proxmox.example.com:8006\nexport PROXMOX_API_TOKEN=PVEAPIToken=user@realm!tokenid=uuid\n\n# Start server\nuvicorn proxmox_sdk.main:app --reload\n```\n\nSee the [Quick Start Guide](https://emersonfelipesp.github.io/proxmox-sdk/quickstart/) for more details.\n\n## Documentation\n\n- **[Home](https://emersonfelipesp.github.io/proxmox-sdk/)** - Overview and features\n- **[Installation](https://emersonfelipesp.github.io/proxmox-sdk/installation/)** - Installation options (pip, uv, Docker, source)\n- **[Quick Start](https://emersonfelipesp.github.io/proxmox-sdk/quickstart/)** - 5-minute getting started guide\n- **[SDK Mock Usage](https://emersonfelipesp.github.io/proxmox-sdk/sdk-mock/)** - Using the SDK with mock data (no server required)\n- **[Mock API](https://emersonfelipesp.github.io/proxmox-sdk/mock-api/)** - Mock mode guide with custom data\n- **[Real API](https://emersonfelipesp.github.io/proxmox-sdk/real-api/)** - Real Proxmox integration guide\n- **[API Reference](https://emersonfelipesp.github.io/proxmox-sdk/api-reference/)** - Endpoint documentation\n- **[Development](https://emersonfelipesp.github.io/proxmox-sdk/development/)** - Contributing guide\n- **[IDE Support](https://emersonfelipesp.github.io/proxmox-sdk/ide-support/)** - VS Code, Pylance, and type-checking setup\n- **[Architecture](https://emersonfelipesp.github.io/proxmox-sdk/architecture/)** - How it works internally\n- **[FAQ](https://emersonfelipesp.github.io/proxmox-sdk/faq/)** - Frequently asked questions\n\n## Environment Variables\n\n### Mock Mode\n- `PROXMOX_API_MODE` - Set to \"mock\" (default) or \"real\"\n- `PROXMOX_MOCK_SCHEMA_VERSION` - Version tag to use (default: \"latest\")\n- `PROXMOX_MOCK_DATA_PATH` - Path to custom mock data file (default: \"/etc/proxmox-sdk/mock-data.json\")\n- `PROXMOX_MOCK_STORE` - Mock state backend: \"sqlite\" (default), \"shared-memory\", or \"dict\"\n- `PROXMOX_MOCK_STATE_PATH` - Optional SQLite mock-state database path\n\n### Real Mode\n- `PROXMOX_API_MODE` - Set to \"real\" to enable Proxmox integration\n- `PROXMOX_URL` - Proxmox server URL (e.g., \"https://proxmox.example.com:8006\")\n- `PROXMOX_API_TOKEN` - API token (recommended, format: \"PVEAPIToken=user@realm!tokenid=uuid\")\n- `PROXMOX_USERNAME` - Username (fallback, format: \"user@realm\")\n- `PROXMOX_PASSWORD` - Password (fallback)\n- `PROXMOX_API_VERIFY_SSL` - Verify SSL certificates (default: true)\n\n### Server\n- `HOST` - Host to bind to (default: \"0.0.0.0\")\n- `PORT` - Port to bind to (default: \"8000\")\n\n## Development\n\n```bash\n# Install dependencies\nuv sync --extra test\n\n# Run tests\npytest\n\n# Run linting\nruff check .\nruff format --check .\n\n# Run type checks\nuv run ty check proxmox_sdk tests --output-format concise\nuv run pyright proxmox_sdk\n```\n\n## IDE Support\n\nOpen the repository in VS Code. When prompted, install the recommended\nextensions (`ms-python.vscode-pylance`, `ms-python.python`,\n`charliermarsh.ruff`). Pylance picks up types from the installed package\nautomatically because `proxmox_sdk` ships a `py.typed` PEP 561 marker.\n\nType checking uses two gates: `ty` for fast project checks and `pyright` for\nPylance-compatible diagnostics. Both run at `typeCheckingMode = \"basic\"`:\n\n```bash\nuv run ty check proxmox_sdk tests --output-format concise\nuv run pyright proxmox_sdk\n```\n\n## Docker\n\nAll 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:\n\n| Variant | Tags | Description |\n|---------|------|-------------|\n| **Raw** (default) | `latest`, `\u003cversion\u003e` | Pure uvicorn, HTTP only. Smallest image. |\n| **Nginx** | `latest-nginx`, `\u003cversion\u003e-nginx` | nginx terminates HTTPS via mkcert; proxies to uvicorn. |\n| **Granian** | `latest-granian`, `\u003cversion\u003e-granian` | [Granian](https://github.com/emmett-framework/granian) (Rust ASGI server) with native TLS via mkcert. No nginx. |\n\n\u003e **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.\n\n### Raw image (default)\n\nPlain uvicorn on HTTP — the simplest option for local dev or when you put your own proxy in front.\n\n```bash\ndocker pull emersonfelipesp/proxmox-sdk:latest\ndocker run -d -p 8000:8000 --name proxmox-sdk emersonfelipesp/proxmox-sdk:latest\n```\n\nBuild from source:\n\n```bash\ndocker build -t proxmox-sdk:raw .\ndocker run -d -p 8000:8000 proxmox-sdk:raw\n```\n\n### Nginx image (nginx + mkcert HTTPS + uvicorn)\n\n**nginx** terminates HTTPS on `PORT` (default **8000**) using certificates from [mkcert](https://github.com/FiloSottile/mkcert) and proxies to **uvicorn** on `127.0.0.1:8001`. **supervisord** manages both processes.\n\n```bash\ndocker pull emersonfelipesp/proxmox-sdk:latest-nginx\ndocker run -d -p 8443:8000 --name proxmox-sdk-nginx \\\n  emersonfelipesp/proxmox-sdk:latest-nginx\n```\n\nBuild from source:\n\n```bash\ndocker build --target nginx -t proxmox-sdk:nginx .\ndocker run -d -p 8443:8000 proxmox-sdk:nginx\n```\n\n### Granian image (granian + mkcert HTTPS)\n\n[Granian](https://github.com/emmett-framework/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.\n\n```bash\ndocker pull emersonfelipesp/proxmox-sdk:latest-granian\ndocker run -d -p 8443:8000 --name proxmox-sdk-granian \\\n  emersonfelipesp/proxmox-sdk:latest-granian\n```\n\nBuild from source:\n\n```bash\ndocker build --target granian -t proxmox-sdk:granian .\ndocker run -d -p 8443:8000 proxmox-sdk:granian\n```\n\n### mkcert environment variables (nginx and granian images)\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `PORT` | `8000` | Port the server listens on |\n| `MKCERT_CERT_DIR` | `/certs` | Directory where certs are stored |\n| `MKCERT_EXTRA_NAMES` | — | Extra SANs (commas or spaces), e.g. `proxmox-api.lan,10.0.0.5` |\n| `CAROOT` | — | Mount a volume here to persist the local CA across container restarts |\n| `APP_MODULE` | `proxmox_sdk.mock_main:app` | ASGI app to run (change to `proxmox_sdk.main:app` for real mode) |\n\n```bash\ndocker run -d -p 8443:8000 --name proxmox-sdk-tls \\\n  -e MKCERT_EXTRA_NAMES='myhost.local,192.168.1.10' \\\n  -e APP_MODULE='proxmox_sdk.main:app' \\\n  emersonfelipesp/proxmox-sdk:latest-nginx\n```\n\nTo run a shell instead of starting the server, pass a command (the entrypoint delegates to it):\n\n```bash\ndocker run --rm emersonfelipesp/proxmox-sdk:latest-nginx sh\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femersonfelipesp%2Fproxmox-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Femersonfelipesp%2Fproxmox-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Femersonfelipesp%2Fproxmox-sdk/lists"}