Proxmox: install qemu-guest-agent in a cloud-init VM

You created a VM from a cloud image (Debian, Ubuntu), ticked the QEMU Guest Agent option, and yet Proxmox shows "Guest Agent not running" and no IP address in the Summary tab. This is the classic trap: cloud images do not ship the agent, and the option on the VM side is not enough. This guide explains the three pieces of the puzzle and the three ways to install the agent, with the most reliable one (cloud-init) tested on PVE 9. It is aimed at anyone automating cloud-init VMs, and it also shows how to enable the agent on an existing VM without cutting it off by force.

What you will learn

• Why "Guest Agent not running" appears even though the option is ticked.
• Install the agent cleanly through cloud-init (snippet).
• The alternatives (virt-customize, post-boot) and their pitfalls.
• Enable the agent on an existing VM with a clean shutdown, without qm stop.
• Check that the agent answers and that the IP address comes back.

What is the agent for?

The qemu-guest-agent is a small daemon that runs inside the guest and gives Proxmox three services:

• reporting the IP address in the Summary tab (without it, the network works, but the address is not displayed on the hypervisor side);
• a shutdown request sent to the guest: qm shutdown goes through the agent if it is active, otherwise through ACPI, which the guest also handles cleanly;
• consistent backups: Proxmox freezes the filesystem (fsfreeze) while the snapshot is taken.

ACPI is therefore not a brutal shutdown: it is a shutdown request, like pressing the power button of a server. The brutal shutdown is qm stop, which cuts the VM off like pulling a plug and which Proxmox logs as a qmstop task. Without the agent, this request is still possible; the agent is mostly there to report the IP address and to freeze the filesystem before a snapshot.

The real problem: three pieces, not one

The most common mistake is to believe that a single action is enough. Three are needed, spread across both sides.

Step	Where	Command	If forgotten
Enable the channel	VM side	qm set <vmid> --agent enabled=1	the agent cannot communicate
Install the package	guest side	apt install qemu-guest-agent	nothing listens on the channel
Enable the service	guest side	systemctl enable --now qemu-guest-agent	the agent is there but inactive

Swipe to see more

Cloud images do not have the package: steps 2 and 3 are almost always the missing ones.

Method 1: cloud-init (the most reliable)

For a cloud-init VM, you ask cloud-init to install and enable the agent on first boot, through a snippet (a small cloud-init configuration file). The storage must accept the snippets content type (on local, in /var/lib/vz/snippets/).

1. Create the snippet in /var/lib/vz/snippets/qemu-agent.yaml:

   #cloud-config
   packages:
     - qemu-guest-agent
   runcmd:
     - systemctl enable --now qemu-guest-agent

2. Attach the snippet to the VM with vendor=, never user=:

   qm set <vmid> --cicustom "vendor=local:snippets/qemu-agent.yaml"

vendor, not user

Proxmox already generates the cloud-init user configuration (user, SSH keys, password from the Cloud-Init tab). Overwriting it with user= would destroy those settings, whereas vendor= is added without breaking anything. You can inspect what Proxmox generates with qm cloudinit dump <vmid> vendor.

On the lab, the proof that it works, once the VM has started:

qm agent <vmid> ping
# (no error = the agent answers)
qm agent <vmid> network-get-interfaces
# ... "ip-address": "192.168.10.238" ...  -> the IP address comes back

cloud-init installs nothing without a network on first boot

The packages: key of cloud-init only installs the package if the network is available on first boot. If the network is missing at that moment, the apt install fails silently and no new attempt is made afterwards. For VMs without a network at boot, prefer baking the package into the template.

Method 2: virt-customize (watch out for the trap)

You can also inject the agent into the image before creating the VM:

apt install -y libguestfs-tools
virt-customize -a debian-13-genericcloud-amd64.qcow2 \
  --install qemu-guest-agent \
  --run-command 'systemctl enable qemu-guest-agent' \
  --truncate /etc/machine-id

virt-customize that "succeeds" without installing anything

A trap seen first-hand and reproducible: virt-customize prints "Finishing off" as if everything went well, but the package is missing (qemu-guest-agent.service could not be found). Cause: the libguestfs appliance has no DNS, so the apt install fails silently. Fix on PVE 9: install dhcpcd-base on the host before running virt-customize (without it, the appliance does not configure its network). Then check that the package is really there, and do not trust the "Finishing off".

The --truncate /etc/machine-id prevents all clones from inheriting the same machine-id (and therefore the same DHCP address).

Method 3: inside the already running VM

The most direct route when the VM is already running and you can connect to it:

apt update && apt install -y qemu-guest-agent
systemctl enable --now qemu-guest-agent

Enable the channel without forcing the VM off

Whichever installation method you used, the channel is set on the Proxmox side, and the VM must start again from a full boot for the guest to see it. The clean sequence never cuts the VM off by force:

qm shutdown <vmid>
qm set <vmid> --agent enabled=1
qm start <vmid>

qm shutdown asks the guest to shut down: through the agent if it is already active, otherwise through ACPI, which the guest handles cleanly. The option is then set on the stopped VM, and qm start restarts it with the new hardware.

A reboot from inside the guest is not enough

The --agent enabled=1 option adds a virtio-serial port, which is virtual hardware. It only appears in the guest at the next start of the VM, that is after a complete shutdown followed by a qm start. A reboot from the guest OS does not create it: this is the most common mistake. The device expected in the guest is /dev/virtio-ports/org.qemu.guest_agent.0; if it is missing, the full start did not happen.

Keep qm stop for a VM that no longer responds: it cuts the VM off without warning the guest, with the risk of lost writes, and Proxmox logs it as a qmstop task.

Check it end to end

# from the Proxmox host
qm agent <vmid> ping                    # no error = communication OK
qm agent <vmid> network-get-interfaces  # the IP address must appear

# inside the guest
ls -l /dev/virtio-ports/org.qemu.guest_agent.0   # the device exists
systemctl is-active qemu-guest-agent             # active

The complete proof comes down to two findings: qm agent ping returns no error, and the IP address appears in the Summary tab of the interface.

Common pitfalls

Symptom	Cause	Solution
"Guest Agent not running" persists	option ticked but package missing	install qemu-guest-agent in the guest
Still nothing after the install	the VM has not done a full boot since the option was enabled	qm shutdown, qm set <vmid> --agent enabled=1 on the stopped VM, then qm start
virt-customize "succeeds" but the agent is missing	no DNS in the appliance	dhcpcd-base on the PVE 9 host
systemctl finds nothing	you are looking for qemu-ga	the unit is qemu-guest-agent, the process is qemu-ga
Clones with the same IP address	identical machine-id	--truncate /etc/machine-id on the image

Swipe to see more

Put it into practice

In the lab, the agent of VM 180 does not answer, for one of two causes drawn at random: the device is not enabled in Proxmox, or the package is missing from the guest. You diagnose, then restore the agent without forcing the VM off. The validation checks that the device is enabled, that qm agent 180 ping answers, that the /dev/virtio-ports/org.qemu.guest_agent.0 channel exists in the guest and that an address comes back. It also reads the task log: a single qmstop since the start of the lab fails the criterion.

Guided lab Practice

Learn how to do it

Restore the QEMU guest agent without forcing the VM off

$ dsoxlab run pve-reparer-agent

Environment: VM·Duration: ~25 min

How it is checked: the state of the machine is checked, not the command you typed.

First time? What DSOXLab is and how to install it

DSOXLab is the command line that prepares a disposable environment (an isolated shell or a VM), runs the lab scenario, then checks the real state of the system and computes a score. Nothing is installed or broken on your workstation.

It needs Python 3.11 or later, uv or pipx, and git. The installation guide details these prerequisites; on Windows, or on a Mac without Python, use the appliance instead.

This lab starts virtual machines: it also needs ansible-playbook, a hypervisor (KVM or Incus), Terraform and hardware virtualization (/dev/kvm), which inside a VirtualBox VM means nested virtualization. The first time, dsoxlab start pve-reparer-agent checks all of it before creating the machines. Prepare your machine for vm labs.

Install the CLI and add the catalogue, once:

uv tool install dsoxlab   # or: pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/proxmox-dsoxlab-training

Before you run the lab, check:

• DSOXLab installed
• catalogue available
• compatible environment (isolated shell or VM)

To check, nothing is probed from this page: run dsoxlab doctor. Read the diagnosis

Run this lab, then validate your work:

dsoxlab run pve-reparer-agent
dsoxlab check pve-reparer-agent

See every lab: dsoxlab list-labs. Track your progress: dsoxlab progress. The full dsoxlab guide covers scoring and the pitfalls.

Key takeaways

• The agent needs three pieces: the channel (--agent enabled=1), the package and the service. The option alone is not enough.
• For a cloud image, the reliable method is cloud-init with a vendor= snippet (packages: qemu-guest-agent).
• virt-customize fails silently without DNS: install dhcpcd-base on the PVE 9 host and check the result.
• After --agent enabled=1, chain qm shutdown, the option on the stopped VM, then qm start. ACPI asks for a clean shutdown; qm stop is the forced shutdown, reserved for a VM that no longer responds.
• Proof: qm agent ping without an error and the IP address in the Summary tab.

×

See in the glossary →