Skip to content

Install Qemu Guest Agent

Install qemu-guest-agent on Debian, Ubuntu, Rocky Linux, and AlmaLinux virtual labs to improve host-guest communication.

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 update
sudo dnf check-update
sudo pkg update

Install the qemu-guest-agent

sudo apt install qemu-guest-agent
sudo dnf install qemu-guest-agent
sudo pkg install qemu-guest-agent

Enable the service to start on boot

sudo systemctl enable qemu-guest-agent
sudo systemctl enable qemu-guest-agent
sudo sysrc qemu_guest_agent_enable="YES"

Start the service

sudo systemctl start qemu-guest-agent
sudo systemctl start qemu-guest-agent
sudo service qemu-guest-agent start

Verify 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.

Type to search…

↑↓ navigate↵ selectEsc close