JohnTheNerd/proxmox-swap

Proxmox Swap Manager is a nicely focused project with a very clear use case: sharing one Proxmox host between two mutually exclusive workloads without relying on social coordination or manual start/stop steps. The README does a good job explaining the privacy/resource-sharing motivation, the IDLE -> ACTIVE -> WARNING -> GRACE session model, and the operational safety measures. I especially liked that the implementation treats Proxmox as the source of truth during startup, uses a watchdog loop to remediate invalid states, and keeps an audit log for session starts, kicks, recovery actions, and owner overrides. That is the right instinct for a tool whose failure mode could mean both workloads running at once.

The code is also more complete than the repository name first suggests. app/state.py has a deliberate switching protocol with precondition checks, cooldowns, verification, and undo paths. app/pve.py supports both LXC and QEMU by resolving VM IDs through cluster resources, which makes the project more flexible than a single-container script. The auth choices are practical too: trusted-header mode works well behind a reverse proxy, while OIDC support makes the app viable for a small team or homelab with an identity provider. Docker Compose, Swarm examples, secret-file support, and a GitHub Actions container build workflow all make it feel deployable rather than just experimental code.

The main thing I would improve before calling this broadly production-ready is the test story. test_pve_api.py is useful as an integration probe against a real Proxmox environment, but the core state machine deserves automated tests with mocked Proxmox responses: failed host shutdown, failed guest start, both-running recovery, expired sessions, owner vs guest watchdog kicks, and malformed persisted state. I would also fix a few adoption details in the docs: the README says Python 3.12 while pyproject.toml and the Dockerfile use Python 3.14, and OIDC_BASE_URI appears twice in the configuration table. Adding repository topics like proxmox, fastapi, homelab, watchdog, and oidc would help discovery, since the project currently has no stars, forks, or open issues and is still very new.

Overall, this is a specific, useful homelab operations tool with unusually thoughtful safety mechanics for a first public release. With automated tests around the switching invariants and a small documentation cleanup pass, it would be much easier for another Proxmox user to trust it with real workloads.