Docs

• 1: Binary quick start
• 2: Package installation

1 - Binary quick start

Download an archive and SHA256SUMS from GitHub Releases. Choose the Vmango server’s architecture, which may differ from the guest VM’s architecture. No Docker or Go compiler is needed.

Choose an archive

Replace VERSION below with the version shown on the release, without its v prefix.

These are dynamically linked applications. The Windows ZIP includes libvirt DLLs, their dependencies, virsh.exe, license notices and a package manifest. Keep them next to vmango.exe. Linux and macOS use system-installed libvirt libraries. The archives include a minimal configuration and this guide.

Linux prerequisites

On Ubuntu 22.04 or newer:

sudo apt-get update
sudo apt-get install libvirt0 libvirt-clients genisoimage openssh-client

genisoimage supplies the mkisofs and isoinfo commands used to create and read cloud-init config drives. Other distributions need equivalent packages; Alpine’s musl runtime is not supported by this Linux archive.

macOS prerequisites

Install Homebrew, then:

brew install libvirt dvdrtools

The binary links to Homebrew’s libvirt in /opt/homebrew. dvdrtools provides mkisofs and isoinfo. This does not configure a local hypervisor: use a remote Linux/KVM host for this quick start. Local QEMU/HVF needs separate setup. The binary is not Developer ID signed or notarized; follow your organization’s policy for downloaded executables.

Windows prerequisites

Extract the complete ZIP. The bundled libvirt client does not run a Windows hypervisor. Use a remote Linux/KVM host with authenticated TLS (qemu+tls). Follow libvirt’s TLS setup and Windows client certificate locations. Do not substitute an unauthenticated public TCP connection.

The bundled Windows client cannot use SSH: qemu+ssh is unsupported on Windows, and the Fedora MinGW libvirt build has both qemu+libssh and qemu+libssh2 disabled. Installing OpenSSH or adding a libssh2 DLL does not enable these transports. CI probes all three URIs with the packaged virsh.exe; using SSH would require a different libvirt build and a separate connection test.

The archive does not include ISO tools. Creating or reading cloud-init config drives requires Windows-compatible mkisofs.exe and isoinfo.exe on PATH. Until those are installed, use Windows for managing existing VMs; provisioning with config drives is not covered by the Windows CI smoke check. Event hook scripts also require a sh executable. See the verification scope below.

Verify and unpack

On Linux, from the directory containing the archive and checksums:

sha256sum --ignore-missing -c SHA256SUMS
tar -xzf vmango-VERSION-linux-x64.tar.gz
cd vmango-VERSION-linux-x64
cp vmango.quickstart.conf vmango.conf

On macOS:

shasum -a 256 vmango-VERSION-macos-arm64.tar.gz
# Compare the result with this archive's line in SHA256SUMS.
tar -xzf vmango-VERSION-macos-arm64.tar.gz
cd vmango-VERSION-macos-arm64
cp vmango.quickstart.conf vmango.conf

On Windows, in PowerShell:

Get-FileHash .\vmango-VERSION-windows-x64.zip -Algorithm SHA256
# Compare the result with this archive's line in SHA256SUMS.
Expand-Archive .\vmango-VERSION-windows-x64.zip -DestinationPath .
Set-Location .\vmango-VERSION-windows-x64
Copy-Item vmango.quickstart.conf vmango.conf
# Make the bundled virsh and any tools in this directory available by name.
$env:PATH = "$PWD;$env:PATH"

Connect a hypervisor

For Linux running on an already configured KVM host, verify access as the same user who will run Vmango:

virsh -c qemu:///system list --all

For Linux or macOS connecting to a remote host, first configure SSH key access and confirm the host key interactively. The remote account must have permission to use the libvirt system socket:

ssh [email protected]
virsh -c 'qemu+ssh://[email protected]/system' list --all

Use that URI in vmango.conf. On Windows, test the configured TLS connection with the bundled client:

.\virsh.exe -c 'qemu+tls://hypervisor.example.com/system' list --all

Edit the archive’s minimal configuration:

key_file = "./authorized_keys"

libvirt "local" {
    uri = "qemu:///system"
    config_drive_pool = "default"
}

web {
    listen = "127.0.0.1:8080"
    base_url = "http://localhost:8080"
    session_secret = "REPLACE_WITH_RANDOM_SECRET"
    media_upload_tmp = "."

    user "admin" {
        hashed_password = "REPLACE_WITH_GENPW_OUTPUT"
    }
}

Replace uri with the verified URI. The name local is just a label; you can rename it to describe a remote host. Use an existing, active storage pool for config_drive_pool. For example, check virsh -c URI pool-list --all.

Set a password and start

Run ./vmango genpw (PowerShell: .\vmango.exe genpw), enter your administrator password, and paste the printed bcrypt hash into hashed_password without changing its $ characters. Run this in an interactive terminal.

Generate a session secret with openssl rand -hex 32 on Linux/macOS. In Windows PowerShell, use:

$bytes = New-Object byte[] 32
$rng = [System.Security.Cryptography.RandomNumberGenerator]::Create()
$rng.GetBytes($bytes)
$rng.Dispose()
[BitConverter]::ToString($bytes).Replace('-', '').ToLowerInvariant()

Paste the result into session_secret. Keep vmango.conf private to your user. Start from the extracted directory, which must be writable:

./vmango web -c vmango.conf

On Windows:

.\vmango.exe web -c vmango.conf

Open http://localhost:8080/ and log in as admin with the password you just entered. The node should appear after login. Stop the foreground server with Ctrl+C.

To create a VM, put a cloud-init-enabled image in a storage pool on the hypervisor, then add an image block with its path and OS metadata from vmango.dist.conf. Configure networking on the hypervisor first. The binary archive does not configure KVM, pools, networks or guest images for you.

For remote browser access, serve Vmango through HTTPS, set web.base_url to that public URL and enable web.session_secure. Preserve Host, Origin and Sec-Fetch-Site in the reverse proxy. Remote VNC access needs HTTPS too. SSH console forwarding also needs ssh locally and socat or nc on the hypervisor. TLS-connected consoles require network reachability to the host’s VNC port; a successful libvirt TLS connection alone does not tunnel VNC.

Troubleshooting zero nodes

• Check the startup log for the configuration filename. Use -c explicitly if the current directory differs from the extracted archive.
• Define at least one libvirt "name" block. Nodes are configured explicitly, not discovered automatically.
• Read cannot get node / cannot open libvirt connection messages. A failed connection is omitted from the node list.
• Run virsh -c 'EXACT_URI' list --all as the same user and with the same environment. Fix socket permissions, SSH keys, host-key trust or TLS certificates there first. A remote account may need membership in the host’s libvirt group and a new login session.
• Verify the pool exists and is active on that connection. An empty VM list is normal on a new host and does not mean that no nodes are configured.

Verification scope

CI builds each archive, extracts it and checks server startup, login and a node using libvirt’s test:///default driver. Unit tests run on Linux, macOS and Windows. This checks dynamic loading and the HTTP path, not a real hypervisor. Linux and macOS CI also checks an ISO round trip with the installed tools. Windows config-drive tools and real Windows-to-Linux TLS/VM operations require separate integration verification before claiming those deployment scenarios as tested. A successful macOS check does not establish Linux/KVM behavior. Verify VM lifecycle operations on a real hypervisor before release. See the release process.

2 - Package installation

Use the release repositories below. Configure /etc/vmango.conf for your libvirt host and web login before starting the service.

Ubuntu 22.04, 24.04 and 26.04 LTS (amd64)

sudo add-apt-repository ppa:subuk/vmango
sudo apt-get update
sudo apt-get install vmango

The release PPA contains separate Jammy, Noble and Resolute builds.

Debian 12 and 13 (amd64)

Use the Ubuntu 22.04 Jammy build from the release PPA. These are Ubuntu packages, not native Debian builds. The package validation workflow checks installation, server startup, login and a libvirt test node on Debian 12 (Bookworm) and Debian 13 (Trixie). Real KVM operations require separate testing.

Add only the Vmango PPA, with its signing key restricted to this repository:

sudo apt-get update
sudo apt-get install ca-certificates curl gnupg
curl -fsSL 'https://keyserver.ubuntu.com/pks/lookup?op=get&search=0x10538B83BC93D600E0C98A39AF0F396262965789' \
  -o /tmp/vmango-ppa.asc
gpg --show-keys --with-fingerprint /tmp/vmango-ppa.asc

Verify the primary key fingerprint is 1053 8B83 BC93 D600 E0C9 8A39 AF0F 3962 6296 5789, also shown on the PPA overview. Then install the key and add the repository:

sudo install -d -m 0755 /etc/apt/keyrings
sudo install -m 0644 /tmp/vmango-ppa.asc /etc/apt/keyrings/vmango-ppa.asc
printf '%s\n' \
  'Types: deb' \
  'URIs: https://ppa.launchpadcontent.net/subuk/vmango/ubuntu' \
  'Suites: jammy' \
  'Components: main' \
  'Architectures: amd64' \
  'Signed-By: /etc/apt/keyrings/vmango-ppa.asc' \
  | sudo tee /etc/apt/sources.list.d/vmango.sources
sudo apt-get update
sudo apt-get install vmango

Keep Suites: jammy on both Debian versions. Do not replace it with bookworm or trixie, and do not add Ubuntu’s main repositories to Debian. The Go compiler and compiler PPA are not needed to install binary packages.

RHEL 9 and 10 (x86_64)

sudo dnf install -y dnf-plugins-core
sudo dnf copr enable subuk/vmango
sudo dnf install vmango

See the release COPR project for completed builds and repository setup for your system.

Configure and start

Edit /etc/vmango.conf, configure a password and connect a libvirt host as described in the quick-start guide. Package installation does not configure a hypervisor, storage pools or VM images.

On systems where the package installs the systemd unit:

sudo systemctl enable --now vmango