Skip to content
VirtConsole Docs

QEMU guest agent

The QEMU guest agent is a small service inside the guest OS that talks to the hypervisor over a private virtio-serial channel. VirtConsole uses it to run one-off actions inside the guest without needing SSH or a login of its own.

What needs it

Section titled “What needs it”
  • Reset Root/Administrator Password (Settings > Reset Password).
  • Web SSH (temporary key injection for the browser terminal session).
  • Static IP and other network changes pushed from the panel into the guest’s own network configuration.
  • Docker one-click apps (deploy, status checks, logs and control of the managed containers).
  • Kubernetes control-plane certificate operations (kubeadm cert upload and renewal, used internally by cluster management).
  • WireGuard configuration sync.
  • Windows activation (SPLA license activation runs the guest’s own slmgr.vbs through the agent).
  • Creating an image from a running instance.

The agent channel (virtio-serial, org.qemu.guest_agent.0) is built into every VM definition VirtConsole writes, whether or not the guest has the agent installed - nothing changes on the hypervisor side. If the guest never answers, the actions above fail or time out; everything else (power actions, console, backups, firewall rules, migrations) works without it.

Already installed

Section titled “Already installed”

Every VirtConsole cloud image ships the guest agent, enabled and running. An instance deployed or reinstalled from a VirtConsole image needs nothing further.

Install it on an imported or hand-built machine

Section titled “Install it on an imported or hand-built machine”

A machine you brought in yourself - imported from Virtualizor, VMware, Hyper-V, or built from your own ISO - may not have it. Install it inside the guest:

  • Debian / Ubuntu:

    Terminal window
    apt-get install -y qemu-guest-agent && systemctl enable --now qemu-guest-agent

  • RHEL family (AlmaLinux, Rocky, CentOS Stream):

    Terminal window
    dnf install -y qemu-guest-agent && systemctl enable --now qemu-guest-agent

  • Windows: download the virtio-win ISO from fedorapeople.org and run virtio-win-guest-tools.exe from it. This installs the VirtIO serial driver and the “QEMU Guest Agent” Windows service together. Verify with:

    Terminal window
    Get-Service QEMU-GA

No restart is needed on Linux; the service starts immediately. On Windows the installer may prompt for a reboot to finish the VirtIO driver install.

Verify it is working

Section titled “Verify it is working”

There is no dedicated “agent reachable” badge on a KVM instance page. Confirm it functionally instead:

  • Settings > Reset Password succeeds instead of failing.
  • Web SSH opens a terminal instead of failing to connect.
  • On a Proxmox-managed instance, the manage page’s Network tab shows a populated Guest IPs table; “Guest IP discovery is unavailable for this instance” means the agent has not answered yet.
  • From the console: systemctl status qemu-guest-agent on Linux, or Get-Service QEMU-GA on Windows.
Section titled “Related”