Skip to main content

Guest Agent

The guest agent is a small service that runs inside your virtual machine and reports information back to the Gallium Console, such as IP addresses and operating system details.

What the Guest Agent Provides​

When the guest agent is connected, the Console displays the following information on the Guest Agent tab:

  • Operating System — the OS name reported by the guest
  • Version — the OS version
  • Kernel Release and Kernel Version (Linux guests)

IP addresses reported by the guest agent also appear on the VM's Network Interfaces tab.

Installing the Guest Agent​

During VM Creation​

The Install Guest Agent checkbox in the Configuration section of the VM creation form is enabled by default. When enabled, the guest agent is installed automatically via cloud-init when the VM first boots.

tip

For most Linux VMs created from templates, the guest agent is installed automatically with no manual action needed. Leave the Install Guest Agent checkbox enabled during VM creation.

tip

For Windows VMs, the guest agent is not installed via cloud-init. Instead, it is included on the configuration drive attached during VM creation and can be installed automatically via an Autounattend answer file or manually after setup.

Manual Installation​

If a VM was created without the guest agent — for example, if cloud-init was not used or the checkbox was unchecked — you can install it manually inside the VM.

Linux — install the qemu-guest-agent package using your distribution's package manager:

  • Debian/Ubuntu: sudo apt install qemu-guest-agent
  • RHEL/CentOS/Fedora: sudo dnf install qemu-guest-agent

After installation, start the service:

sudo systemctl enable --now qemu-guest-agent

Windows — install the QEMU guest agent from the configuration drive attached to the VM at creation time:

  1. Open File Explorer and navigate to the CONFIGDRIVE volume.
  2. Run guest-agent\qemu-ga-x86_64.msi and follow the installer prompts.

Alternatively, install silently from an elevated Command Prompt:

msiexec /i D:\guest-agent\qemu-ga-x86_64.msi /qn
info

The drive letter for the configuration drive may vary. Look for a volume labeled CONFIGDRIVE in File Explorer or Disk Management.

For a fully automated installation using an Autounattend answer file, the guest agent is installed automatically by SetupComplete.cmd after OOBE finishes. See Windows Configuration for details.

Checking Guest Agent Status​

Navigate to the VM's detail page and select the Guest Agent tab.

  • Connected — the agent is running and reporting. Operating system information and IP addresses are displayed.
  • Guest Agent Disconnected — the agent is not responding. The VM may be running but the agent is not installed or has not started yet.
info

Guest agent information is only available when the virtual machine is running.