Commands

• Install: uv sync
• Run app: uv run python -m pve_vm_setup
• Run live diagnostics: uv run python -m pve_vm_setup --doctor-live
• Run tests: uv run pytest
• Run read-only live tests: uv run pytest -m live
• Run create-gated live tests: uv run pytest -m live_create
• Lint: uv run ruff check .
• Format: uv run ruff format .

Live configuration

Start from .env.example and provide the Proxmox credentials in .env.

Additional live-access controls:

• PROXMOX_VERIFY_TLS=false disables certificate verification for internal/self-signed installs
• PROXMOX_API_BASE=/api2/json makes the API base explicit
• PROXMOX_PREVENT_CREATE=false allows VM creation by default; set it to true to block creates
• PROXMOX_ENABLE_TEST_MODE=true enables scoped test mode for live creates
• When test mode is enabled, PROXMOX_TEST_NODE, PROXMOX_TEST_POOL, PROXMOX_TEST_TAG, and PROXMOX_TEST_VM_NAME_PREFIX are required and are used to constrain and mark created VMs

Engineering rules

• Write tests before implementation
• Prefer small PR-sized tasks
• Keep business logic out of widgets where possible
• Field-like widgets should default to compact 3-row controls with no empty spacer line between the value row and the border
• Every screen must have empty/loading/error coverage
• Every interactive feature needs at least one Pilot test
• Visual changes should be covered by snapshot tests