Skip to content

Proxmox Provider

PteroCloud connects to Proxmox VE over its HTTPS API using a dedicated API token. The panel never SSHes into a PVE node and never stores a human password.

Connection model

Panel ── HTTPS (API token) ──► Proxmox VE API
   │
   ├─ discovery: nodes, storage, bridges, templates, QEMU guests
   ├─ power actions: start / shutdown / reboot / stop
   └─ task polling: UPID status
  • Read-only connections sync discovery data but reject every mutation with PROVIDER_READ_ONLY.
  • Disabled connections accept no work at all.
  • A circuit breaker marks a connection degraded after 3 consecutive transient failures and offline after 6.

Setup order

  1. Create the API token on a PVE node.
  2. Grant least-privilege permissions.
  3. Choose a TLS trust mode.
  4. Register the connection and Test Connection.
  5. Map discovered assets (nodes, storage, bridges, templates).

Connection test ladder

The probe runs synchronously and answers a structured ladder:

api_reachable → auth_valid → version_read → nodes_readable
             → qemu_listing_readable → storage_readable

A healthy result (connected: true) persists the provider version and cluster name, resets the circuit breaker, and reports per-step outcomes plus privilege warnings from a read-only permission inspector. Auth failures land on authentication_error, TLS failures on tls_error, permission failures on permission_error.

php artisan pterocloud:proxmox:test <provider_uuid>

Sync

Area Cadence
Nodes every minute
Instances every two minutes
Assets (storage, networks, templates) every fifteen minutes

Manual sync:

php artisan pterocloud:proxmox:sync <provider_uuid> --all

Provider jobs run on the pterocloud-provider queue.