Hyperlite is a self-hosted virtualization manager: a FastAPI backend that drives libvirt/QEMU-KVM (virtual machines) and LXC (containers), and a React web dashboard. It aims at the day-to-day experience of tools such.
Project status: early stage. Hyperlite is developed by a small team and has been tested on a few physical machines and many throw-away VMs. There is no stable release yet, interfaces may change, and it has not been independently security-audited. Read Limitations before running it anywhere that matters.
- Virtual machines: create, start/stop, delete, clone, snapshots, templates, cloud-init, resource limits (cgroups), installation from any ISO through the console, disk import/export, UEFI with Secure Boot and TPM 2.0, USB and PCI passthrough, CPU pinning.
- Containers: LXC containers built from a Debian base or from any Docker Hub / OCI image (no Docker daemon needed), with a web SSH terminal; Kubernetes (k3s) clusters on Hyperlite VMs.
- Storage: local directory pools, shared NFS pools (with the NFS version chosen at creation), ZFS pools (VMs on zvols, native ZFS snapshots), iSCSI targets.
- Networking: virtual networks (NAT, isolated, bridge on a host bridge, NIC, bond or VLAN interface), per-VM firewall (libvirt nwfilter) and per-network firewall (iptables on the bridge). VLAN tags and trunks on a VM interface, on VLAN-aware Linux bridges (made so from the dashboard, with a rollback), Open vSwitch or SR-IOV.
- Cluster: nodes that are all equal: the configuration is replicated on every node (Corosync and
hyperlite-cfs), any node serves the dashboard and the API, and there is no controller to lose. A node that loses the quorum changes nothing until it is back, and the majority's changes always win. Created and joined from the dashboard (the Cluster page, in the sidebar's Cluster group), with live migration and a compatibility check, node maintenance mode, a rolling update, and every node's tasks, audit log and backups seen from any node. High availability restarts the protected VMs of a lost member on another one, automatically, once that member is known to be stopped (its BMC powered it off, or its watchdog reset it), by priority and preferred nodes, with admission control. A host across a WAN, where Corosync cannot run, can still be driven over SSH from one node (qemu+ssh://, no agent, a manual takeover withhyperlite-promote): deprecated, it goes with API v2, replaced by one view over several autonomous sites (#656). - Backups: hot and cold VM backups with a checksummed manifest and automatic verification, UEFI NVRAM and TPM state included, schedules per VM or per group, retention by count or daily/weekly/monthly, file-level restore, replication to another site every few minutes (incremental), and recovery of a lost site.
- Updates: one update for Hyperlite and the node's Debian packages, with the release notes and the reboot needed shown first, an automatic return to the previous version if the new one does not start, a stable or test channel per node, Debian's security updates every night, an update from a signed file for a node without network, and a rolling update of a cluster (each node emptied by live migration first).
- Operations: metrics history (Prometheus format, export to InfluxDB and Graphite), audit journal, task tracking, job engine, outgoing notifications (webhook, email).
- Security: local accounts, LDAP / Active Directory, optional OpenID Connect single sign-on, two-factor authentication (TOTP or WebAuthn security keys and passkeys), API tokens, fine-grained permissions (roles, groups, pools, per-resource ACL).
- Web console: VNC console and SSH terminals in the browser, host shell for administrators.
- Workstation access: the
hyperliteclient opens SSH or remote desktop from the user's own computer through a tunnel over the server's HTTPS port, with sign-in through the web interface (SSO and 2FA apply), per-VM permission and audit.
See docs/features.md for details and the user guide for how to use each feature.
For Windows guests, including Windows Server 2025, see the Windows installation guide. The Windows profile defaults to SATA storage to avoid loading a separate storage driver. See guest compatibility and hardware profiles for tested scope and firmware limitations.
- A 64-bit x86 Linux host with hardware virtualization (KVM). Debian 12 and 13 are the tested platforms.
- libvirt and QEMU (
qemu-kvm,libvirt-daemon-system), pluslibvirt-daemon-driver-lxcfor containers. - Python 3.11 or newer.
- Node.js 20.19 or newer, only to build the dashboard from source.
Hyperlite runs as root (it manages libvirt, networks, storage and a host shell). Install it on a dedicated machine or VM.
Download hyperlite-appliance-amd64.iso (with its .sha256 and .sig files, see docs/deployment.md to verify them), write it to a USB stick and boot the target machine. The installation is unattended and erases the disks. See docs/deployment.md for the details.
Replace <repository-url> with the address of the Hyperlite APT repository (the public mirror is https://hyperlite-hv.github.io; see docs/deployment.md for its limitations):
curl -fsSL <repository-url>/hyperlite-archive-keyring.asc | gpg --dearmor -o /usr/share/keyrings/hyperlite-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hyperlite-archive-keyring.gpg] <repository-url> stable main" > /etc/apt/sources.list.d/hyperlite.list
apt update && apt install hyperliteThe service listens on https://<host>:8000 with a self-signed certificate. The initial administrator password is written to /root/.hyperlite-initial-password.
See CONTRIBUTING.md.
| Document | Content |
|---|---|
| docs/user-guide.md | User guide: how to use every feature of the web interface |
| docs/webui-test-matrix.md | Web UI end-to-end coverage matrix and how to run it |
| docs/onboarding.md | Access and working rules for a new contributor |
| docs/architecture.md | Components, data model, security model |
| docs/features.md | Feature reference and known scope limits |
| docs/configuration.md | Environment variables and files |
| docs/workstation-access.md | SSH and remote desktop from a workstation (hyperlite client) |
| docs/deployment.md | Installation, updates, APT repository, ISO, publishing |
| docs/api.md | API conventions: API v1, names, errors, clusters |
| CONTRIBUTING.md | Development setup, checks, workflow |
| SECURITY.md | Reporting vulnerabilities, security notes |
- Early-stage software; no stability promise for the API, the database schema or the packaging.
- The service and the host shell run as root. Do not expose port 8000 to untrusted networks.
- The appliance installer asks for the
rootpassword; the initial Hyperliteadminpassword is random and shown on the console banner. Change it after the first sign-in. - The TLS certificate is self-signed by default (browsers will warn); a certificate can be imported or obtained through ACME (Let's Encrypt).
- A cluster needs a low-latency network between its nodes (Corosync). Hosts driven over SSH from one controller (deprecated) depend on it: its configuration is copied to them every 15 minutes, and taking over after its loss is a manual command (docs/cluster-failover.md). Without the quorum a cluster node changes nothing, VMs included: a two-node cluster needs a QDevice, or
hyperlite-cfs expected-votesonce a node is known to be down for good. - Automatic high availability needs proof that a lost member stopped: a BMC (IPMI or Redfish) or an armed watchdog. Without either, its VMs are left to an administrator. It covers VMs whose disks are on a share that locks across nodes (NFS, SMB); hosts driven over SSH get a dry run only.
- ZFS pools are created on loopback files by the web interface (single node); Ceph is not supported.
- The CI only publishes (package, ISO, APT repository); the tests (backend unit and API tests, dashboard lint and build, the Playwright end-to-end suite, the
hyperlite-cfstests) are run locally before a pull request. Multi-node operations (NFS, ZFS, migration, HA) are still mostly verified by hand on real machines.
Hyperlite is distributed under the PolyForm Noncommercial License 1.0.0. You may use, study, modify and share it for noncommercial purposes (personal use, hobby projects, research, education, nonprofit organizations, and testing). Commercial use, including offering it as a paid or hosted service, requires a separate permission from the author. If you want to evaluate Hyperlite for a business purpose, please ask first by opening an issue or contacting the maintainer through the repository. This is not legal advice; read the license text.
The command-line client and its Go library (cli/, which the Terraform / OpenTofu provider is built on) are under the Mozilla Public License 2.0, as most Terraform providers are: a company may use them in its automation.
Third-party components keep their own licenses, see THIRD_PARTY_NOTICES.md.