PiVirt — Cloud Virtualization Platform

The modern, cloud-native successor to VMware vSphere — decoupled 3-tier architecture, declarative GitOps engine, and self-describing bare-metal resilience.

Quick Start Architecture Deep Dive CLI Cheat Sheet View on GitHub

The Modern Successor to Legacy Virtualization

PiVirt is an open, distributed virtualization management platform engineered by Progressive Innovation LAB (PiLab). Built from the ground up to overcome the licensing traps, monolithic fragility, and proprietary lock-in of legacy hypervisors like VMware vSphere (ESXi & vCenter), PiVirt combines bare-metal KVM/QEMU performance with modern cloud-native principles: ConnectRPC / gRPC, declarative YAML manifests, mTLS service mesh, and self-describing host storage.

The Three-Tier Architecture

PiVirt introduces a clean, three-tier architectural boundary that mirrors and modernizes the enterprise virtualization stack:

Tier	Component	Open / Free	VMware Analogue	Kubernetes Analogue	Primary Role
Host	`pivirtd`	Open Source	`vmkernel`	CRI / `containerd`	Standalone host executor daemon. Low-level QEMU/KVM lifecycle, QMP control, veth bridges, and local disk volumes. Zero cluster awareness.
Node	`agent`	Free (≤ 4 nodes)	`hostd` / Host Client	`kubelet`	Node supervisor & local control plane. Manages datastores, templates, standard vSwitches, and local identity (standalone) or streams mTLS telemetry & tasks (managed).
Cluster	`director`	Enterprise / Paid	`vCenter`	`kube-apiserver`	Centralized cluster control plane. Multi-node scheduling (DRS), cluster HA, Distributed Virtual Switches (DVS), cross-host IPAM, and multi-tenancy.

Host Tier — pivirtd (The Modern vmkernel)

Ultra-lightweight, crash-isolated hypervisor daemon. Talks directly to Linux KVM, QEMU, and local disks over a private Unix socket (/var/run/pivirt/pivirtd.sock). Because it has zero cluster logic, it almost never restarts — ensuring management agent crashes or network reboots never kill running VMs.

Node Tier — agent (The Modern hostd)

Node supervisor and service mesh gateway. Can run completely standalone without a cluster director (ideal for edge, homelabs, and 4-node clusters) with local authentication and Direct Console UI (virt-appliance), or enroll into a director via mTLS to execute distributed tasks and stream live telemetry.

Cluster Tier — director (The Modern vCenter)

Intelligent cluster control plane. Delivers automated VM placement and load balancing (DRS), cluster-wide distributed virtual switches (DVS), cross-host overlay networking (VXLAN/VNI), multi-tenant isolation, and a modern React administrative console.

Wire Protocol — virtpb (Shared Schemas)

Type-safe ConnectRPC & gRPC foundation. Standardized Protobuf contracts shared across the entire ecosystem, enabling first-class SDKs, high-speed streaming, and declarative resource validation.

Why PiVirt? Architectural Superpowers

Declarative GitOps Engine

Manage your entire virtualization topology declaratively using Kubernetes-style YAML manifests. Use pivirtctl apply -f and pivirtctl delete -f across VirtualMachines, Networks, StoragePools, VirtualDisks, and IPPools with automated dependency ordering and reverse-dependency cascading deletion.

Self-Describing Hosts & Zero-Loss DR

The physical hosts are the ultimate ground truth. pivirtd persists declarative YAMLs locally while the agent stamps cluster identities (pivirt.hu/uid, pivirt.hu/owner-org, pivirt.hu/generation). If the central Director database is ever destroyed, a new Director reconstructs cluster state and tenancy directly from bare metal.

Two-Generation Integrity

Host-local generation (metadata.generation) and cluster generation (pivirt.hu/generation) are decoupled. Local host maintenance and direct CLI adjustments never trigger false cluster drift or race conditions with the cluster controller.

Zero-Downtime Management

Strict process boundaries guarantee that agent upgrades, certificate rotations, or transient network partitions will never affect hypervisor execution. Your workloads stay online no matter what happens to the management tier.

Core Platform Components

graph TB
    subgraph "Clients & Operators"
        UI["Director Web UI<br/>(React Admin Console)"]
        PVCLI["pvcli / pivirtctl<br/>(Operator CLIs)"]
        DCUI["appliance / DCUI<br/>(Bubble Tea TUI)"]
    end

    subgraph "Cluster Control Plane — Paid / Enterprise"
        DIRECTOR["director (vCenter Analogue)<br/>DRS Scheduler • DVS • IPAM • Multi-Tenancy"]
        STATE_DB[("Cluster State Database")]
        DIRECTOR <--> STATE_DB
    end

    subgraph "Node Tier — Free (≤ 4 Nodes) / Standalone or Managed"
        AGENT["agent (hostd Analogue)<br/>Node Supervisor • Datastores • Local Identity • TaskExecutor"]
        ISCSIMAN["iscsiman<br/>iSCSI & OCFS2 Cluster Storage"]
    end

    subgraph "Host Tier — Free / Bare-Metal Executor"
        PIVIRTD["pivirtd (vmkernel Analogue)<br/>QEMU/KVM • AF_PACKET DHCP • Metadata Service"]
        KVM["Linux KVM / QEMU Hypervisor"]
        PIVIRTD --> KVM
    end

    UI <-->|ConnectRPC / WebSockets| DIRECTOR
    PVCLI <-->|ConnectRPC| DIRECTOR
    PVCLI <-->|ConnectRPC| AGENT
    PVCLI <-->|Unix Socket gRPC| PIVIRTD
    DCUI <-->|PAM / Local APIs| AGENT

    DIRECTOR <-->|mTLS NodeSession Stream| AGENT
    AGENT <-->|Unix Socket gRPC| PIVIRTD
    AGENT <-->|gRPC| ISCSIMAN

Tailored For Your Workflow

Cloud & VPS Operators

Manage multi-tenant VM lifecycles, storage pools, custom images, and quotas with pvcli, pivirtctl, or the interactive TUI.

Explore pvcli Reference →

Hypervisor Administrators

Direct single-node hypervisor management via pivirtd and pivirtctl over low-latency Unix sockets with zero external dependencies.

Learn about pivirtd →

Kubernetes & Cloud Native

Zero-touch provisioning of Talos Linux Kubernetes clusters with embedded DHCP and cloud metadata services.

Talos Kubernetes Guide →

Developers & Integrators

Build custom controllers using type-safe ConnectRPC APIs, Protobuf specs, and Go/Python/TypeScript SDKs.

ConnectRPC API Docs →

Quick Launch: Start in 60 Seconds

# Download pvcli (Cluster & Node CLI)
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

# Download pivirtctl (Host-level Direct CLI)
curl -L https://github.com/pilab-cloud/pivirtd/releases/latest/download/pivirtctl-linux-amd64 -o /usr/local/bin/pivirtctl
chmod +x /usr/local/bin/pivirtctl

apiVersion: pivirt.hu/v1
kind: VirtualMachine
metadata:
  name: web-server
  labels:
    environment: production
    tier: frontend
spec:
  cpu:
    cores: 2
  memory:
    sizeBytes: 4294967296  # 4 GiB
  disks:
    - name: root-disk
      sizeBytes: 21474836480 # 20 GiB

# Apply declarative resource directly
pivirtctl apply -f vm.yaml

# Query with label selector
pivirtctl get vms -l "environment=production"

# Inspect status
pivirtctl describe vm/web-server

# Clean up with cascade deletion
pivirtctl delete vm/web-server

Quick Links & Resources

System ArchitectureDeep dive into the 3-tier architecture, mTLS session streams, and disaster recovery.

CLI Quick ReferenceOne-liner cheat sheet for all common CLI commands and ops runbooks.

Development WorkflowBranching strategy, conventional commits, and CI/CD.

Troubleshooting GuideDiagnostic trees for network, disk lock, and boot issues.