Skip to content

Native KVM Provider

The Native KVM provider is PteroCloud's own virtualization backend. Proxmox remains a fully supported primary provider; Native KVM is an additional provider, not a replacement.

Architecture

Pterodactyl → PteroCloud → ProviderManager
                              ├── ProxmoxProvider
                              └── NativeKvmProvider
                                        │  (HTTPS, outbound only)
                                        ▼
                              PteroCloud Agent API
                                        │
                                        ▼
                              pterocloud-agent
                                        │  (local socket only)
                                        ▼
                              libvirt → QEMU/KVM → VM

The panel never SSHs into a Native KVM node. The node runs a dedicated pterocloud-agent that performs only predefined, semantic operations. There is no arbitrary shell task type and no command-execution endpoint.

Lifecycle

  1. Enrollment — an admin generates a one-time, expiring enrollment token in the panel. The agent exchanges it for a long-lived credential.
  2. Registration — the agent registers the host as a hypervisor and reports its capabilities (CPU topology, KVM/libvirt availability, IOMMU, nested virtualization, hugepages, storage backends, networks).
  3. Heartbeat — periodic heartbeats. Silence beyond the threshold marks the hypervisor degraded/offline; running guests are not assumed dead.
  4. Operations — the control plane dispatches named tasks (create, start, stop, storage, network) to the agent.
  5. Revocation — a credential can be revoked; it is rejected on the next call.

Safety invariants

  • VMs are owned by libvirt/QEMU at runtime. Panel crash, agent crash, Redis loss or a license outage never stops a VM.
  • Revoking an agent never stops VMs.
  • External libvirt domains are never auto-adopted; orphans are never deleted.
  • VM identity is UUID/metadata based — a domain name is not ownership.
  • Capabilities reflect real support only (unknown = unavailable).

Paths

Path Contents
/etc/pterocloud/ Config + credentials (0600).
/var/lib/pterocloud/ State.
/var/log/pterocloud/ Logs.
/run/pterocloud/ Runtime.

What this build does and does not do

Implemented: the Go agent (run | enroll | status | diagnostics | config-check | version and read-only host/compute/storage/network/hardware inspection), read-only host discovery, honest capability reporting, one-time hashing enrollment tokens, per-node revocable credentials, lightweight heartbeat, secure panel transport, secret redaction, and node classification (MANAGED / EXTERNAL / ORPHANED / MISSING_PROVIDER).

Not implemented / not tested: VM provisioning, disk creation, storage driver execution, bridge/TAP/NAT, snapshots, backups, migration, HA and PCI/GPU passthrough. Live libvirt/QEMU integration is NOT TESTED (there is no libvirt on the development host); /dev/kvm discovery was verified. The panel-side agent API endpoints and real libvirt binding are the next build phases.

Pages