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

🚀 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.

📚 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