The QEMU guest agent is a small service inside a VM that lets the hypervisor ask the guest to do things: shut down cleanly, report its IP addresses, freeze filesystems for consistent snapshots, or set a user password. VPS panels and Proxmox rely on it for several features.
Before you start
- A KVM VM you can log in to, and host access to edit the VM if the channel is missing.
Add the agent channel on the host
Most tools add it automatically (virt-install's newer defaults, Proxmox with Options → QEMU Guest Agent → Enabled). With plain libvirt, check virsh dumpxml vmname for:
<channel type='unix'>
<target type='virtio' name='org.qemu.guest_agent.0'/>
</channel>If missing, add it with virsh edit and power-cycle the VM (a reboot inside the guest is not enough).
Install in a Linux guest
sudo apt install -y qemu-guest-agentAlmaLinux/Rocky: sudo dnf install -y qemu-guest-agent. Then:
sudo systemctl enable --now qemu-guest-agentIf it fails to start, the virtio channel is missing on the host.
Install in a Windows guest
Run virtio-win-guest-tools.exe from the virtio-win ISO, which installs the agent as the QEMU Guest Agent service. See install a Windows VM on KVM.
Test from the host
virsh qemu-agent-command web01 '{"execute":"guest-ping"}'An empty {"return":{}} means it works.
Useful things the agent enables
| Task | Command |
|---|---|
| Show guest IPs | virsh domifaddr web01 --source agent |
| Clean shutdown via agent | virsh shutdown web01 --mode agent |
| Freeze / thaw filesystems | virsh domfsfreeze web01 / virsh domfsthaw web01 |
| Consistent snapshot | virsh snapshot-create-as web01 snap1 --disk-only --quiesce |
| Set a user password | virsh set-user-password web01 root 'NewPass' |
| Guest info | virsh guestinfo web01 |
See KVM snapshots for quiesced snapshots.
Security considerations
- The agent lets the host run privileged operations in the guest. That is expected on a VPS (the provider already controls the hardware), but you can restrict commands with the agent's allow/block lists.
- Disable
guest-execand file commands if you do not need them.
Troubleshooting
- "Guest agent is not responding": service not running, or channel missing; check
systemctl status qemu-guest-agent. - Freeze fails on Windows: VSS service disabled; enable Volume Shadow Copy.
- Panel shows no IP: install the agent and enable it in the VM options.
Frequently asked questions
Do I need the agent on my VPS?
It is recommended: it makes backups more consistent and panel shutdowns cleaner.
Is it the same as VMware Tools?
Similar role, for QEMU/KVM.
Does it use network access?
No, it talks over a virtio-serial channel, not the network.