Skip to content

Install the Native Agent

The native agent runs on a KVM host and executes instance, storage and network operations on behalf of the control plane.

Not tested against live libvirt

The agent's discovery, enrollment, heartbeat and diagnostics are implemented. Live libvirt/QEMU binding has not been tested on hardware in this build. Do not treat Native KVM provisioning as production-proven.

Requirements

  • A Linux host with KVM available (/dev/kvm) and QEMU/libvirt installed.
  • Outbound HTTPS from the host to the panel (the panel never dials in).
  • Root (or equivalent) to install the binary, config and service.

Install

  1. Place the pterocloud-agent binary on the host (for example at /usr/local/bin/pterocloud-agent) and make it executable.
  2. Create the config and state directories with safe permissions:
install -d -m 0750 /etc/pterocloud /var/lib/pterocloud /var/log/pterocloud /run/pterocloud
  1. Write /etc/pterocloud/agent.toml (or the platform's default config path) pointing at the panel URL. Keep the credential file 0600; the agent writes it during enrollment.

Verify the binary

pterocloud-agent version
pterocloud-agent config-check
pterocloud-agent diagnostics

diagnostics prints a sanitized report: hostname, machine id, OS/kernel/arch, CPU topology, memory, KVM presence/accessibility, libvirt/QEMU availability, storage roots and network interface count. It never prints credentials.

Commands

Command Purpose
run Run the agent daemon.
enroll Enroll this host using a one-time token.
status Show local agent status.
diagnostics Sanitized host/libvirt diagnostics.
config-check Validate configuration without network mutation.
domain Read-only domain operations (domain inspect <uuid>).
reconcile Report instance drift (read-only).
storage / network Read-only storage/network status.
compute / hardware / iommu Read-only compute, PCI and IOMMU status.
verify Read-only end-to-end configuration and readiness check.
migration Read-only migration inspection.
version Print build and protocol versions.

Run as a service

Create a systemd unit that runs pterocloud-agent run, restarts on failure, and runs as a dedicated user with access to /dev/kvm and libvirt. The agent sends heartbeats; without a credential it runs in discovery-only mode.

Next