Virtu

A dual-interface, high-performance virtualization management platform.

[!WARNING] Work in Progress: This project is under active development. Expect breakage, rough edges, and evolving APIs or interfaces here and there.

---

⚡ Overview

Virtu manages libvirt-based virtualization infrastructure (KVM/QEMU) across single hosts and multi-node clusters. It shares a unified Crystal core driving two interfaces:

• Virtu Web (WUI): A reactive hypermedia web dashboard built with Kemal, Blueprint, and Datastar (v1.0.4).
• Virtu Desktop (GUI): A native desktop client built with GTK4 and Libadwaita.

✨ Features

• Native Libvirt C-FFI Core: Written in Crystal with non-blocking, fiber-aware libvirt C bindings and per-node connection pooling.
• Dual Interfaces: Manage cluster nodes from the browser (WUI) or natively on the desktop (GUI) across domain lifecycles, cloning, snapshots, storage pools/volumes, virtual networks, host network interface transactions, secrets, NWFilters, and telemetry.
• Hardware & XML Management: Configure domain firmware, topology, memory backing, devices, VFIO PCI passthrough, and raw Libvirt XML definitions.
• Sharded State Cache: Per-node background workers combine Libvirt lifecycle push events with background reconciliation so UI reads do not block on hypervisor I/O.
• Secrets Vault & Network Filters: Manage Ceph, LUKS, and VNC secrets alongside Libvirt NWFilter firewall rules and interface bindings.

📸 Gallery

🚀 Getting Started

Prerequisites

On Fedora:

# Enable Crystal COPR repository and install dependencies
sudo dnf copr enable -y zawertun/crystal
sudo dnf install crystal shards libvirt-devel gtk4-devel libadwaita-devel gobject-introspection-devel

# Add user to libvirt, kvm, and qemu groups for non-root hypervisor access
sudo usermod -aG libvirt,kvm,qemu $USER
newgrp libvirt

Ensure Crystal >= 1.20.2 and development headers for libvirt, gtk4, and libadwaita are installed.

[!NOTE] Ensure system packages are installed before running shards install. If package installation occurs afterwards, run ./bin/gi-crystal or make to generate missing GObject Introspection bindings.

Build & Run

# 1. Install dependencies
shards install

# 2. Build binaries (development or release)
make          # Dev build (fast compilation)
make release  # Production build (optimized)

# 3. Run interface
./bin/virtu-wui  # Web UI
./bin/virtu-gui  # Desktop GUI

Useful Commands

• make check (or make test) — Run the unit and controller spec test suite
• make test-e2e — Run the 5-tier end-to-end integration test suite
• make test-browser — Run browser-based integration specs via Selenium and Broadway
• make format — Format Crystal codebase (crystal tool format)
• make lint — Run Ameba static analysis, ESLint, and Stylelint
• make security — Run Flaw security scanner
• make doc — Build Sphinx HTML documentation
• make dev — Run development server with auto-reload (sentry)
• make install — Install release binaries, desktop entry, systemd unit, and WUI assets
• make uninstall — Remove installed binaries, desktop entry, systemd unit, and assets

System Integration & Contrib

System integration assets (systemd service, desktop launcher, and Fedora RPM spec) are located in contrib/:

# Install release binaries and system assets (defaults to /usr/local)
sudo make install

# Enable and start the background WUI daemon
sudo systemctl daemon-reload
sudo systemctl enable --now virtu-wui.service

# Launch the native desktop client from your launcher or terminal
virtu-gui

See contrib/README.rst for full deployment instructions and RPM packaging with mock.

Configuration

All configuration is via environment variables. VIRTU_CLUSTER_CONFIG (path to cluster.yaml, see cluster.example.yaml) is the only one most deployments need; the rest have safe defaults.

📚 Technical Documentation

Detailed architecture documentation, technical specs, Architecture Decision Records (ADRs), and the project roadmap can be found in the docs/ directory.

🤝 Contributing

We welcome contributions! Please review our Contributing Guidelines for environment setup, testing standards, Conventional Commits, and code quality requirements.

1. Fork the project.
2. Create your feature branch (git checkout -b feature/my-feature).
3. Commit your changes (git commit -s -m 'feat(scope): add some feature').
4. Push to the branch (git push origin feature/my-feature).
5. Open a Merge Request on GitLab.

---

Co-developed by Rénich Bon Ćirić & Gemini AI Pair-Programmer