Learn Cloud Hypervisor - Installation & Build

#Introduction

After understanding Cloud Hypervisor's architecture in episode 2, it's time for your first real action: installing the binary on your host. In episode 3 we cover two installation paths — prebuilt binary for speed and building from source for full control — then verify the installation and make sure the KVM foundation is ready.

The "prebuilt or build it yourself" decision isn't just about convenience. In production, the prebuilt binary from an official release is the sanest choice because it's CI-tested and signed. Building from source is useful when you want to trim features, apply patches, or contribute to the project. We cover both.

#Installation Prerequisites

Before installing, make sure the required toolchain is present. For the prebuilt binary, you only need a compatible glibc (or use the static variant). To build from source, prepare the Rust toolchain:

Check Rust toolchain

rustc --version
cargo --version

If it's not installed, install it via rustup:

Install Rust via rustup

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"

Note

Building Cloud Hypervisor requires a relatively recent Rust version because it uses the latest compiler features. If cargo build fails with a toolchain version error, run rustup update stable first.

#Installing via Prebuilt Binary

The fastest way is to download the official release from GitHub. For this series we use v53.0 (released 12 July 2026). Choose the file that matches your host architecture:

Download the static x86_64 binary

wget https://github.com/cloud-hypervisor/cloud-hypervisor/releases/download/v53.0/cloud-hypervisor-static-x86_64
chmod +x cloud-hypervisor-static-x86_64
sudo install cloud-hypervisor-static-x86_64 /usr/local/bin/cloud-hypervisor

For aarch64, change the filename to cloud-hypervisor-static-aarch64. The static variant bundles all dependencies into a single file, so it doesn't depend on the system's library versions — very helpful when copying the binary to another host.

#Building from Source with Cargo

If you want to compile it yourself, clone the official repository then build:

Build from source

git clone https://github.com/cloud-hypervisor/cloud-hypervisor.git
cd cloud-hypervisor
cargo build --release

cargo build --release produces the binary at target/release/cloud-hypervisor. This process takes a while (from a few minutes to tens of minutes depending on hardware) because it compiles hundreds of crates. Finish by copying the binary to PATH:

Install the built binary

sudo install -D target/release/cloud-hypervisor /usr/local/bin/cloud-hypervisor

Tip

The official repo provides scripts/dev_cli.sh and scripts/run_cli.sh, which bootstrap the build environment inside a container — useful if you don't want to install a system toolchain. For contributions, read CONTRIBUTING.md; a correct local build is only the first step.

#setcap: Permission to Create TAP

As mentioned in episode 0, creating a TAP device requires CAP_NET_ADMIN. Grant the capability to the binary so it can create TAPs without being root:

Grant net_admin capability

sudo setcap cap_net_admin+ep /usr/local/bin/cloud-hypervisor
getcap /usr/local/bin/cloud-hypervisor

getcap must show cap_net_admin=ep. Without this, running a VM with --net tap=... will fail with a permission error. If you don't want to rely on setcap, run cloud-hypervisor as root — but that isn't best practice (episode 12).

#Verifying the Installation

#Version and Features

Check Cloud Hypervisor version

cloud-hypervisor --version

The output looks like cloud-hypervisor v53.0 along with a commit hash. To see which features are enabled in this binary, use --help:

Full help

cloud-hypervisor --help | head -60

cloud-hypervisor --help shows all global options (kernel, firmware, cpus, memory, disk, net, fs, etc.) that we'll use throughout the series. Read it carefully — the options here are your main daily interface.

#Verifying KVM and CPU Virtualization

Cloud Hypervisor can't run without KVM. Verify the foundation:

Verify KVM

ls -l /dev/kvm
grep -cE "(vmx|svm)" /proc/cpuinfo

The number from grep -cE "(vmx|svm)" is the count of logical CPUs that support virtualization. If it's zero, check the virtualization setting in BIOS/UEFI, or use a cloud instance with nested virtualization (episode 19). If /dev/kvm doesn't exist but the CPU flags do, load the kernel module:

Load KVM modules

sudo modprobe kvm
sudo modprobe kvm_intel   # untuk Intel; kvm_amd untuk AMD

#The Quickest Install Test

Verify that the VMM can interact with KVM by running an empty VM (no disk, just booting a kernel if available). For now, just make sure the startup process doesn't immediately error out on KVM:

Try KVM initialization

cloud-hypervisor --cpus boot=1 --memory size=256M

Without a kernel, this command will stop with a message about missing firmware/kernel — that's normal and actually proves KVM was initialized successfully. In episode 4 we'll provide a kernel and actually boot.

Warning

Don't run cloud-hypervisor without setcap or inside an environment without /dev/kvm, then conclude the VMM is broken. Always follow a diagnostic order: check /dev/kvm, check setcap, then check the VM configuration. This saves a lot of debugging time in the episodes ahead.

#Conclusion

Key takeaways:

Download the prebuilt v53.0 binary for tested results, or cargo build --release for full control.
Grant setcap cap_net_admin+ep so TAPs can be created without root.
cloud-hypervisor --version and cloud-hypervisor --help are the first verification gateways.
/dev/kvm + the vmx/svm flags are absolute prerequisites; load KVM modules if needed.
Test KVM initialization with a kernel-less VM before preparing boot assets.

In the next episode, episode 4, we'll do our first boot: Linux & UEFI — direct boot with --kernel vmlinux and PVH, then firmware boot with hypervisor-fw and CLOUDHV.fd (edk2) for full OSes. This is the first moment your VM truly comes alive!