Getting Started with PiVirt

QuickstartLinux / KVMGo 1.22+

This guide walks you through installing PiVirt (pvcli), setting up host prerequisites, and launching your first virtual machine in minutes.

---

Prerequisites

Before installing PiVirt, ensure your host environment meets the following requirements:

Linux Kernel & KVM

Linux host running kernel 5.10+ with hardware virtualization (/dev/kvm) enabled in BIOS/UEFI.

System Resources

Minimum 4GB RAM and 20GB free disk space for host services and initial OS images.

Administrative Access

root or sudo access required for KVM device management and network bridge setup.

Build Tools (Optional)

Go 1.22+ is only required if you choose to build pvcli and pivirtd from source code.

Hardware Virtualization Check

Verify hardware virtualization support before proceeding by running kvm-ok or ls -l /dev/kvm.

---

Quick Installation

Select your preferred installation method below:

Ubuntu / Debian (APT)

Install pivirtd (hypervisor daemon) and pivirtctl (host management CLI) directly from the official PiLab Package Repository (dl.pilab.hu), built via GoReleaser:

# 1. Add PiLab GPG signing key
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://dl.pilab.hu/pivirt.gpg | sudo gpg --dearmor -o /etc/apt/keyrings/pilab.gpg

# 2. Add PiLab APT repository
echo "deb [signed-by=/etc/apt/keyrings/pilab.gpg] https://dl.pilab.hu/deb stable main" | sudo tee /etc/apt/sources.list.d/pilab.list

# 3. Update & Install pivirtd (bundles pivirtd + pivirtctl)
sudo apt-get update
sudo apt-get install -y pivirtd

# 4. Enable and start the service
sudo systemctl enable --now pivirtd

RHEL / Rocky / Fedora (RPM)

Install pivirtd and pivirtctl via YUM/DNF from the official PiLab RPM repository:

# 1. Add PiLab RPM repository
sudo tee /etc/yum.repos.d/pilab.repo << 'EOF'
[pilab]
name=PiLab Packages
baseurl=https://dl.pilab.hu/rpm
enabled=1
gpgcheck=1
gpgkey=https://dl.pilab.hu/pivirt.gpg
EOF

# 2. Install pivirtd
sudo dnf install -y pivirtd

# 3. Enable and start the service
sudo systemctl enable --now pivirtd

Pre-built Binary (pvcli)

Download the latest pre-compiled pvcli executable directly into your PATH:

# Download executable
curl -L https://github.com/pilab-dev/pivirt/releases/latest/download/pvcli-linux-amd64 -o /usr/local/bin/pvcli

# Make executable
chmod +x /usr/local/bin/pvcli

# Verify version
pvcli version

Build from Source

Compile the binaries directly from the official source repository:

1. Clone Repository:

   git clone https://github.com/pilab-dev/pivirt.git
   cd pivirt

2. Compile Binary:

   make build-pvcli

3. Install to PATH:

   sudo cp bin/pvcli /usr/local/bin/

Docker Container

Run pvcli inside an isolated container with host KVM pass-through:

docker run --rm -it \
  --privileged \
  -v /dev/kvm:/dev/kvm \
  pilab-cloud/pvcli:latest vm list

---

Launching Your First Virtual Machine

Follow these step-by-step instructions to initialize PiVirt, pull an operating system image, and boot a virtual machine instance:

1. Initialize CLI Configuration

   Generate your user configuration file at ~/.config/pvcli/config.yaml:

   pvcli config init

2. Discover and Pull an OS Image

   List available OS images managed by osinfodb and pull Ubuntu 24.04:

   # List available images
   pvcli image list
   
   # Download Ubuntu 24.04 image
   pvcli image pull ubuntu-24.04

   Image Metadata & Signatures

   OS images pulled via PiVirt are automatically verified using GPG signatures and SHA256 checksums.

3. Create the Virtual Machine Instance

   Specify your VM configuration via CLI flags or launch the interactive configuration wizard:

   # Create with declarative CLI flags
   pvcli vm create \
     --name web-server \
     --image ubuntu-24.04 \
     --cpus 2 \
     --memory 4G \
     --disk 20G \
     --network bridge=virbr0
   
   # Or run without flags for the interactive TUI wizard
   pvcli vm create

4. Start and Access the Virtual Machine

   Power on the VM instance and connect via serial console or VNC:

   # Power on the virtual machine
   pvcli vm start web-server
   
   # Inspect runtime details (IP, TAP interface, VNC port)
   pvcli vm info web-server
   
   # Attach to serial console
   pvcli vm console web-server

   VNC Graphics Access

   If VNC is enabled in your VM spec, attach using any standard VNC viewer: vncviewer localhost:5900.

---

Troubleshooting Common Issues

KVM Unavailable

If KVM acceleration is missing:

# Verify KVM support
kvm-ok

# Load host kernel modules
sudo modprobe kvm_intel  # For Intel CPUs
sudo modprobe kvm_amd    # For AMD CPUs
sudo modprobe vhost_net

Permission Denied on /dev/kvm

Add your user to the kvm system group to access /dev/kvm without root:

sudo usermod -aG kvm $USER
# Log out and log back in for group changes to take effect

Bridge Network Missing

If virbr0 does not exist on your host, create a default Linux bridge:

cat > /etc/netplan/01-bridge.yaml <<EOF
network:
  version: 2
  bridges:
    virbr0:
      interfaces: [eth0]
      dhcp4: yes
EOF
sudo netplan apply

# Verify bridge creation
brctl show virbr0

---

Next Steps

VM Lifecycle ManagementLearn how to start, stop, snapshot, clone, and migrate virtual machines.

Storage ArchitectureConfigure local qcow2, raw disks, LVM pools, iSCSI targets, and OCFS2.

Virtual NetworkingConfigure bridge networking, VLAN tagging, VXLAN overlays, and SR-IOV.

Cluster ManagementSet up multi-node PiVirt clusters with high availability and live migration.