This README is the one indexed from the repository at its latest ref, not from the tag for this version.

Virtu

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

---

⚡ Overview

Virtu provides comprehensive management for libvirt-based infrastructure (KVM/QEMU) with absolute focus on concurrency and speed. It features a unified core driving two first-class interfaces:

• Virtu Web (WUI): A lightning-fast, reactive hypermedia web dashboard powered by Kemal, Blueprint, and Datastar.
• Virtu Desktop (GUI): A fully native, highly responsive desktop client built with GTK4 and Libadwaita.

✨ Features

• Blazing Fast: Written purely in Crystal with non-blocking, fiber-based C-FFI libvirt bindings.
• Dual Interfaces with 100% Feature Parity: Manage your cluster from the browser (WUI) or natively on the desktop (GUI) with identical capabilities across VM operations, cloning, snapshots, storage, networks, secrets, and telemetry.
• Advanced Hardware Management: virt-manager style hardware configurations, dynamic hot-plugging, and direct XML manipulation.
• Zero-Friction State: A centralized background daemon seamlessly syncs VM state to clients without blocking OS threads.
• Secrets Vault & Network Filters: Full support for Ceph, LUKS, VNC secrets, and Libvirt NWFilter firewall rule chains.

📸 Gallery

Feature	Web Interface (WUI)	Desktop Client (GUI)
Dashboard
Virtual Machines
Storage Pools
Virtual Networks

🚀 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

# 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.md 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.

Variable	Default	Purpose
VIRTU_CLUSTER_CONFIG	cluster.yaml	Hypervisor inventory file
VIRTU_ENV	—	Set to test to isolate specs (disables polling/servers)
VIRTU_NO_POLL	—	Set to true to disable background state polling
VIRTU_NO_RUN	—	Set to true to load the app without serving (specs)
VIRTU_HOST	127.0.0.1	WUI bind address
VIRTU_PORT	5050	WUI bind port
VIRTU_WUI_USER/VIRTU_WUI_PASS	—	WUI basic-auth credentials (required when bound to 0.0.0.0)
VIRTU_PUBLIC_DIR	—	Custom directory override for WUI static assets
VIRTU_CACHE_DIR	/var/lib/libvirt/images/cache	OS image download cache
VIRTU_NODES_PER_PAGE/VIRTU_DOMAINS_PER_PAGE	—	GUI pagination sizes
VIRTU_GRID_COLUMNS	5	Maximum columns for GUI card grids
VIRTU_LOG_LEVEL	info	Logging verbosity (debug, info, warn, error, fatal)

📚 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