#1630·windows

[Feature]: Native QEMU Guest Agent support via GUEST_AGENT environment variable

Author: cedric-marcouxCreated Jan 16, 2026Updated Aug 28, 2026
Labelsenhancement

Is your proposal related to a problem?

The virtio-serial channel is not configured by default. Even with the agent installed in Windows, it cannot communicate with the host. Related to #664

Cannot stop windows properly when rebooting

Describe the solution you'd like.

Add native support for QEMU Guest Agent through a simple GUEST_AGENT=Y environment variable

Describe alternatives you've considered.

ACP shutdown but host is not aware

Additional context

Summary

Add native support for QEMU Guest Agent through a simple GUEST_AGENT=Y environment variable.

Problem

  1. The virtio-serial channel is not configured by default in QEMU
  2. Even with the agent installed in Windows, it cannot communicate with the host
  3. Related to #664 which didn't address the QEMU-side configuration

Tested Solution

Works perfectly with:

ARGUMENTS: "-chardev socket,path=/storage/qga.sock,server=on,wait=off,id=qga0 -device virtio-serial -device virtserialport,chardev=qga0,name=org.qemu.guest_agent.0"

Important: The socket must be in /storage (not /tmp) so it's accessible from the host through the mounted volume.

Results:
- ✅ Socket accessible at ./data/qga.sock from host
- ✅ guest-ping responds: {"return": {}}
- ✅ guest-shutdown triggers proper Windows shutdown

Usage from host

# Graceful shutdown
echo '{"execute":"guest-shutdown"}' | nc -U ./storage/qga.sock

Suggested Implementation

environment:
  GUEST_AGENT: "Y"  # Creates /storage/qga.sock

Benefits

- Graceful shutdown before container stops
- Systemd integration: send shutdown command before host reboot
- Filesystem freeze for consistent snapshots
- Guest monitoring (OS info, users, network)

Tested with Windows 10 LTSC 2021