qemu-guest-agent runs inside the guest and supports host-to-guest management operations.
It does not increase the plan’s CPU, memory, or network entitlement.
Use an authorized guest administrator account with sudo access and a supported distribution package. Keep console recovery available. Run these commands inside the guest, never on the provider host. The host must expose the guest-agent channel. Installing the package alone does not establish host communication. This Linux/FreeBSD tutorial is not a Windows driver or Cloudbase-Init repair procedure. For Windows initialization failures, follow Windows access guidance and contact support.
Preparation - Update the package list
sudo apt updatesudo dnf check-updatesudo pkg updateInstall the qemu-guest-agent
sudo apt install qemu-guest-agentsudo dnf install qemu-guest-agentsudo pkg install qemu-guest-agentEnable the service to start on boot
sudo systemctl enable qemu-guest-agentsudo systemctl enable qemu-guest-agentsudo sysrc qemu_guest_agent_enable="YES"Start the service
sudo systemctl start qemu-guest-agentsudo systemctl start qemu-guest-agentsudo service qemu-guest-agent startVerify communication
On Linux, inspect sudo systemctl status qemu-guest-agent --no-pager after starting the service.
On FreeBSD, use sudo service qemu-guest-agent status. Run sysrc with root privileges or sudo.
Some Linux packages use a static or device-triggered unit. An enable warning does not by itself prove startup failed.
Use the distribution’s unit instructions instead of creating a replacement service blindly.
Confirm the service is active, then check whether Panel receives a fresh guest OS observation. A running guest service does not prove the host can reach it or that a queued password operation completed. Do not repeatedly reset credentials as a communication test.
Troubleshoot and recover
- Package not found: check your distribution release and enabled supported repositories. Do not install an unknown binary.
- Device or channel missing: preserve the service error and ask support to check host-side guest-agent configuration.
- Service fails: inspect its local OS log and distribution documentation before changing service options.
- Panel observation remains unavailable: report the guest service state, UTC time, and redacted error to support.
dnf check-update can return exit code 100 when updates exist. Review upgrades separately during an agreed maintenance window.
Do not disable the agent during provisioning. Coordinate removal with support if host-managed credentials or observations depend on it.
Keep passwords, private keys, and sensitive service logs out of public reports.