Install the Quantix guest agent

The Quantix Agent runs inside a virtual machine and lets Quantix see into it and act on it gracefully. With the agent installed you get:

• the VM's IP addresses, hostname and operating system shown in the VM list and VM details;
• graceful Shutdown and Reboot instead of a hard power-off;
• file browsing, running scripts, and guest password reset;
• consistent snapshots (the file system is paused briefly while a snapshot is taken);
• time synchronisation and display resizing in the console.

Supported guest operating systems

Family	Versions
Linux	Ubuntu 18.04+, Debian 10+, Rocky Linux 8+, CentOS 7+, RHEL 7+, Fedora 35+, openSUSE 15+, Arch Linux, Alpine 3.14+. Other distributions can use the static binary on the agent ISO.
Windows	Windows 10 and 11, Windows Server 2016 to 2025 (64-bit). Windows 7, 8 and 8.1 use the separate legacy Windows ISO.
FreeBSD	13 and 14 (amd64).

Prerequisites

• A running VM. The ISO method needs no network access inside the guest.
• Administrator (root or Administrator) access inside the guest.
• The Quantix Agent Tools ISO available to the host. Hosts download it from the update server set under Admin Panel → Updates → Update settings; see Updates. Hosts without an update server can have the ISO uploaded to their image library instead.

Install on Linux

1. Open the VM and select the Quantix Agent tab. It shows Quantix Agent Not Installed.

2. Under ISO Installation, click Mount Agent ISO. (You can also use Mount Agent ISO from the VM's right-click menu.)

3. In the guest, mount the CD-ROM and run the installer:

   sudo mkdir -p /mnt/cdrom
   sudo mount /dev/cdrom /mnt/cdrom
   sudo /mnt/cdrom/linux/install.sh

   The installer detects the distribution, installs the matching package and starts the quantix-kvm-agent service. Useful options: --auto (no prompts), --uninstall (remove the agent).

4. Eject the ISO from the VM when the installer finishes.

Alternative — One-Click Install. If the guest already runs the standard QEMU guest agent (qemu-guest-agent), click Install Quantix Agent under One-Click Install on the same tab. No ISO or guest login is needed.

Install on Windows

1. Mount the agent ISO as above (Quantix Agent tab → Mount Agent ISO).
2. In Windows, open the CD drive, right-click install.bat and choose Run as administrator. (From PowerShell as administrator: .\install.ps1.)
3. The installer adds the VirtIO serial driver, installs the agent under C:\Program Files\Quantix-KVM\ and starts the LimiQuantix Guest Agent service.

To remove the agent, run uninstall.bat from the same ISO.

Expected result

Within a minute of the service starting:

• the Quantix Agent tab shows a green status dot and the agent version, with the guest's hostname, OS, kernel and IP addresses;
• the VM's Summary tab shows Guest Agent — Status: Connected;
• the VM list shows the VM's IP address;
• Actions → Guest Operations (Shutdown, Reboot, Run Script, Browse Files) become available.

To check from inside the guest:

Guest	Command
Linux	systemctl status quantix-kvm-agent (on Alpine: rc-service quantix-kvm-agent status)
Windows	sc query LimiQuantixAgent

If the agent does not connect

• Agent service not running — start it (sudo systemctl start quantix-kvm-agent, or start LimiQuantix Guest Agent in Windows Services) and check its log: journalctl -u quantix-kvm-agent on Linux, C:\ProgramData\Quantix-KVM\Logs\agent.log on Windows.
• "Quantix Agent Tools ISO not found" when mounting — the host has no update server configured and no local copy of the ISO. Set the update server under Admin Panel → Updates, or upload the ISO to the host's image library.
• Windows shows the agent installed but not connected — the VirtIO serial driver was not installed; run install.bat again as administrator.

The agent's settings file is /etc/quantix-kvm/agent.yaml on Linux and C:\ProgramData\Quantix-KVM\agent.yaml on Windows. The defaults are right for almost every VM.