Install a hypervisor

A hypervisor is the KVM host that runs your customers’ instances. Each hypervisor runs the agent (the installer output still calls it the slave agent), a small service that receives commands from the panel.

Before you begin

• A clean server that meets the hypervisor requirements. No existing control panel, PHP, nginx or Redis installs. The one exception is a Virtualizor KVM node you are about to import: see Migrate from Virtualizor.
• Virtualization enabled in the BIOS. Check with grep -E '(vmx|svm)' /proc/cpuinfo; empty output means VT-x or AMD-V is disabled.
• The management server installed.
• Networking planned. See Networking modes.

Install

Run the command as root. Debian images log you in as root and do not ship sudo. On a host where you are not root and sudo is available, pipe to sudo bash instead of bash.

curl -fsSL https://packages.virtconsole.com/slave/install.sh | bash

The installer detects your OS automatically. It supports:

• Debian 11, 12, 13
• Ubuntu 22.04, 24.04, 26.04 LTS
• RHEL-family 9 and 10 (CentOS Stream, Rocky Linux, AlmaLinux)

On anything else it exits with an “Unsupported distro” message.

Note

On a fresh host the installer creates a virtconsole system user and installs to /opt/virtconsole. A host that already has /opt/hypervisor from an older release is adopted in place. The installer keeps the agent there instead of moving it.

Tip

Set PHP_VERSION (8.3 or 8.4, default 8.4), APP_ROOT or MIRROR_HOST before the command to override the defaults. For example, to install PHP 8.3 instead of the default:

PHP_VERSION=8.3 bash -c "$(curl -fsSL https://packages.virtconsole.com/slave/install.sh)"

The old per-OS scripts (install.debian.sh, install.ubuntu.sh, install.rhel.sh) still exist and run install.sh under the hood, so earlier bookmarks and scripts keep working.

What the installer does

• Installs KVM, QEMU and libvirt with the dependencies VirtConsole needs.
• Installs nginx, PHP-FPM, Redis, supervisor and cron.
• Installs the agent and starts it on port 2443 (HTTPS).
• Prints confirmation when the agent is listening.

Verify

1. Run systemctl status and confirm the agent service is active (running).
2. From the management server, check reachability: curl -k https://203.0.113.10:2443 (use the hypervisor’s IP). Any HTTP response, even an error, proves the port is open.

What happens next

Add the host in the panel: go to Infrastructure > Hypervisors, click Add hypervisor, enter a name and the server’s IP address, choose a Group, and click Add Hypervisor. A hypervisor must belong to a group, so create one first under Infrastructure > Hypervisor Groups if you have none. The panel handshakes with the agent and exchanges an auth token. The full walkthrough is steps 3 and 4 of the quick setup.

Common problems

• The panel cannot reach the agent. Port 2443 is blocked by a firewall or the agent is not running. Check systemctl status on the hypervisor.
• The installer fails on package conflicts. The server is not clean. Reinstall the OS or remove the conflicting packages and retry.
• Running CSF? See CSF firewall.

Related

• Networking modes
• Add a Proxmox VE node
• Add storage
• Updating