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.

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

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.