Bare Metal Installation

Provision PiVirt directly onto physical bare-metal Linux servers using the official package repository (dl.pilab.hu) or standalone binaries.

Prerequisites

Linux host with KVM hardware virtualization enabled (kernel 5.10+)
Root/sudo access for KVM, Open vSwitch, and systemd service management
Minimum Specifications: 4 CPU cores, 8GB RAM, 50GB storage pool space
Supported Distributions: Ubuntu 22.04/24.04 LTS, Debian 12+, RHEL 9+, Rocky Linux 9+

# Update system packages
sudo apt-get update && sudo apt-get upgrade -y

# Install KVM, QEMU, and networking tools
sudo apt-get install -y qemu-kvm bridge-utils openvswitch-switch

# Install iSCSI and storage tools
sudo apt-get install -y open-iscsi multipath-tools ocfs2-tools

# Load and persist KVM kernel modules
sudo modprobe kvm_intel # or kvm_amd
sudo modprobe vhost_net
echo 'kvm_intel' | sudo tee -a /etc/modules-load.d/kvm.conf
echo 'vhost_net' | sudo tee -a /etc/modules-load.d/kvm.conf

# Update system packages
sudo dnf update -y

# Install KVM, QEMU, and networking tools
sudo dnf install -y qemu-kvm bridge-utils openvswitch

# Install iSCSI and storage tools
sudo dnf install -y iscsi-initiator-utils device-mapper-multipath ocfs2-tools

# Load and persist KVM kernel modules
sudo modprobe kvm_intel # or kvm_amd
sudo modprobe vhost_net
echo 'kvm_intel' | sudo tee -a /etc/modules-load.d/kvm.conf
echo 'vhost_net' | sudo tee -a /etc/modules-load.d/kvm.conf

Step 2: Install pivirtd & pivirtctl

pivirtd and its host management CLI pivirtctl are published to the PiLab Package Repository (dl.pilab.hu) via GoReleaser as native .deb and .rpm packages. The package automatically installs binaries in /usr/bin/, creates /etc/pivirtd and /var/lib/pivirt/daemon, installs OVMF firmware variables (/usr/share/pivirtd/assets/OVMF_VARS.fd), and sets up the pivirtd.service systemd unit.

# 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. Install pivirtd package (includes pivirtd + pivirtctl)
sudo apt-get update
sudo apt-get install -y pivirtd

# 4. Start and enable hypervisor daemon
sudo systemctl enable --now pivirtd
sudo systemctl status pivirtd

# 1. Add PiLab YUM/DNF 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 package
sudo dnf install -y pivirtd

# 3. Start and enable hypervisor daemon
sudo systemctl enable --now pivirtd
sudo systemctl status pivirtd

# Download latest pre-built binaries
curl -L https://github.com/pilab-cloud/pivirtd/releases/latest/download/pivirtd-linux-amd64 -o /usr/bin/pivirtd
curl -L https://github.com/pilab-cloud/pivirtd/releases/latest/download/pivirtctl-linux-amd64 -o /usr/bin/pivirtctl
chmod +x /usr/bin/pivirtd /usr/bin/pivirtctl

Step 3: Install Node Agent (`pivirt-agent`)

The node agent provides ConnectRPC APIs, power schedule execution, and secure PiTrust mTLS service mesh communication:

# Download agent binary
curl -L https://github.com/pilab-dev/pivirt/releases/latest/download/pivirt-agent-linux-amd64 -o /usr/local/bin/pivirt-agent
chmod +x /usr/local/bin/pivirt-agent

# Create agent configuration directory
sudo mkdir -p /etc/pivirt-agent/tls

# Create configuration file
sudo tee /etc/pivirt-agent/config.yaml > /dev/null << 'EOF'
server:
  connectrpc:
    addr: "0.0.0.0:8443"
    tls:
      cert_file: "/etc/pivirt-agent/tls/server.crt"
      key_file: "/etc/pivirt-agent/tls/server.key"
      ca_file: "/etc/pivirt-agent/tls/ca.crt"
      client_ca_file: "/etc/pivirt-agent/tls/ca.crt"

  grpc_internal:
    addr: "0.0.0.0:9000"

  metrics:
    addr: "0.0.0.0:8444"
    path: "/metrics"

tls:
  enabled: true
  ca_file: "/etc/pivirt/certs/ca-chain.pem"
  cert_file: "/etc/pivirt/certs/agent-client.crt"
  key_file: "/etc/pivirt/certs/agent-client.key"

backends:
  pivirtd:
    endpoint: "unix:///var/lib/pivirt/daemon/pivirtd.sock"
    timeout: "30s"

logging:
  level: "info"
  format: "json"
  output: "stdout"
EOF

# Create systemd service
sudo tee /etc/systemd/system/pivirt-agent.service > /dev/null << 'EOF'
[Unit]
Description=PiVirt Node Agent
After=network.target pivirtd.service
Requires=pivirtd.service

[Service]
Type=notify
ExecStart=/usr/local/bin/pivirt-agent --config /etc/pivirt-agent/config.yaml
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

# Enable and start agent
sudo systemctl daemon-reload
sudo systemctl enable --now pivirt-agent
sudo systemctl status pivirt-agent

Step 4: Install pvcli & DCUI

pvcli (Operator CLI)
Appliance & DCUI (Host TUI)

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

# Initialize user config
pvcli config init

# Configure local context
pvcli context add local localhost 8443 --insecure
pvcli context switch local

# Install PiVirt Appliance package from dl.pilab.hu
sudo apt-get install -y pivirt-appliance # or: sudo dnf install -y pivirt-appliance

# Start the DCUI on the direct host terminal
sudo appliance

Step 5: Verification & Launch First VM

Verify that the hypervisor daemon, agent, and storage layers are operational:

# 1. Verify daemon socket status
pivirtctl version
pivirtctl vm list

# 2. Pull base OS image
pvcli image pull ubuntu-24.04

# 3. Create and launch virtual machine
pvcli vm create --name web-server --image ubuntu-24.04 --cpus 2 --memory 4G --disk 20G
pvcli vm start web-server
pvcli vm info web-server

pivirtd Overview

Learn about hypervisor daemon settings, QMP, and directory storage pools.
View pivirtd Guide

DCUI Operator Reference

Host console management, network setup, and hardware diagnostics.
View DCUI Reference

Talos Linux Kubernetes

Deploy Kubernetes clusters on PiVirt with zero-touch provisioning.
View Talos Guide

Troubleshooting Guide

Host diagnostic workflows, network debugging, and disk locks.
View Troubleshooting