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

🚀 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 & 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)

📚 Technical Documentation

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

🤝 Contributing

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