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.

To run a container instead, follow Docker installation.

Optional web setup

On macOS and Linux, vmango install --config /absolute/path/vmango.conf starts a temporary loopback wizard for preparing Linux hosts locally or over SSH. It requires a separately supplied pinned Richt executable. Review OS changes, network/storage changes and the final configuration independently; the wizard does not start or restart the Vmango server. See the installer guide for the exact runtime build, prerequisites, permissions and recovery steps. Local macOS hypervisor provisioning and Windows controllers are outside this wizard’s scope. The manual setup below remains available.

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 libvirt@hypervisor.example.com
virsh -c 'qemu+ssh://libvirt@hypervisor.example.com/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 vmango.quickstart.conf and save it as vmango.conf. Keep its shipped namespace, image and cloud blocks. The excerpt below shows only connection and login settings; it is not a complete cloud configuration:

key_file = "./authorized_keys"

namespace "platform" {
    name = "Platform"
    clouds = ["local"]
}

cloud "local" {
    # Keep the shipped images, zone, instance types, network and storage class.
    host "local" {
        uri = "qemu:///system"
        config_drive_pool = "default"
        zone = "local"
        # Keep the shipped reserves, network and storage bindings here.
    }
}

api {
    listen = "127.0.0.1:8080"
    base_url = "http://localhost:8080"
    jwt_signing_key_file = "~/.vmango/jwt_signing_key"

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

Replace uri inside cloud "local" → host "local" with the verified URI. The host name local is its stable identity; connection and backend settings belong directly in that host block. Use an existing, active storage pool for config_drive_pool. For example, check virsh -c URI pool-list --all.

HTTPS

For access from other computers, configure HTTPS either directly in Vmango or through an HTTPS reverse proxy. Native HTTPS uses the existing api.listen address; edit the api block in your configuration:

api {
    listen = ":8443"
    base_url = "https://vmango.example.com:8443"
    tls_cert_file = "/etc/vmango/tls/fullchain.pem"
    tls_key_file = "/etc/vmango/tls/privkey.pem"
    # Preserve your users, signing-key paths and credential-store settings.
}

tls_cert_file contains the PEM server certificate followed by its intermediate certificates, and tls_key_file contains its matching unencrypted PEM private key. Use a certificate valid for the hostname clients connect to and trusted by their browsers. Both files must be readable by the process user (vmango for RPM/DEB services); restrict access to the private key. Absolute paths are recommended; ~/ paths are expanded using the process user’s home directory.

Setting both fields enables HTTPS only on that address, with TLS 1.2 or newer. There is no separate HTTP listener or automatic redirect. Leaving both empty preserves HTTP. Setting just one field, or supplying unreadable, malformed or mismatched files, prevents startup. Port 8443 works without privileged-port permissions in packaged services.

Secure authentication cookies and console wss:// connections are automatic with native HTTPS; session_secure = true is not required. If base_url is set, it must be an absolute HTTPS URL. Set it to the public URL, including a nonstandard port, for OIDC callbacks and absolute shared console links.

Certificate issuance and renewal are managed externally. Vmango loads the certificate and key once at startup; replace them and restart Vmango after renewal. For a packaged service, use systemctl restart vmango.

Behind an HTTPS reverse proxy, leave the TLS file fields empty to keep the upstream listener on HTTP, set base_url to the public HTTPS URL and enable session_secure. Bind the upstream to loopback or a private network. The proxy must preserve the public Host, Origin and Sec-Fetch-Site headers and support WebSocket upgrades.

Manage multiple hosts

One Vmango instance can manage virtual machines across multiple local or remote libvirt hosts from the same web interface. Add a host block inside the cloud for each hypervisor. Host names and connection URIs must be globally unique. The following replaces the cloud "local" block in the quick-start configuration; keep its nested image definitions:

cloud "local" {
    # Keep the nested image definitions from vmango.quickstart.conf here.
    zone "local" {}
    instance_type "small" { cpu = 2 memory_mib = 2048 boot_disk_gib = 20 }
    network "lan" {}
    storage_class "standard" {}

    host "local" {
        uri = "qemu:///system"
        config_drive_pool = "default"
        zone = "local"
        network "lan" { network = "default" }
        storage_class "standard" { pool = "default" }
    }
    host "remote" {
        uri = "qemu+ssh://libvirt@hypervisor.example.com/system"
        config_drive_pool = "default"
        zone = "local"
        network "lan" { network = "default" }
        storage_class "standard" { pool = "default" }
    }
}

This example connects a Linux Vmango server to its local KVM host and a remote host over SSH. Use connection types supported by your server platform; Windows requires remote hosts with authenticated TLS, as described above. Verify each URI and its storage pool as the user running Vmango. Pool names refer to pools on each respective host; they do not create shared storage. Each host contains its connection settings, AZ, logical networks and storage classes together. Multiple hosts can share one AZ. Restart Vmango after changing the configuration. The scheduler selects the host when creating a VM; the user does not select a node. See configured clouds and scheduling.

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.

API JWTs and console links share one Ed25519 signing key, stored as an unencrypted PKCS#8 PEM file with mode 0600. The default is ~/.vmango/jwt_signing_key; override it with api.jwt_signing_key_file. A missing file or contents that cannot be decoded as PEM, including an old hex secret, is replaced automatically at startup. This invalidates old signed tokens and console links. An unsupported or invalid key in a decodable PEM file causes a startup error and is left untouched. Preserve the private file across restarts. Remove the obsolete api.console_signing_key_file and any old inline key settings from configuration. 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. Choose Platform in the Namespace selector, then select the local cloud. Read-only host diagnostics are available under Administration → Clouds → local → Hosts. Stop the foreground server with Ctrl+C.

A namespace groups your machines, disks, keys, templates and tasks into a workspace. The shipped configuration allows Platform to use the local cloud. See Namespaces to add workspaces or use multiple clouds. Existing machines and disks need explicit assignment after an upgrade; find them in Administration and follow the guide’s migration instructions.

To create a VM, first check the cloud catalog and host bindings, then follow the cloud images and provisioning guide to use the shipped lazy downloadable catalog or register a manually prepared source volume on the hypervisor in vmango.conf. Administrators prepare the hypervisor’s pools and networking and configure private host bindings. Users then create machines from catalog references; they do not select raw pools or image paths. The binary archive does not configure KVM, pools or networks for you; a missing downloadable image is prepared when an accepted create task needs it.

For remote browser access, use native HTTPS or an HTTPS reverse proxy and set api.base_url to the public URL. Behind a proxy, enable api.session_secure and preserve Host, Origin and Sec-Fetch-Site. 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 empty clouds or hosts

• Select a namespace and confirm its clouds list includes the desired cloud. An empty selector requires a namespace block in the configuration and a restart. Existing unassigned machines remain visible in Administration inventory.
• Check the startup log for the configuration filename. Use -c explicitly if the current directory differs from the extracted archive.
• Define at least one host "name" inside a cloud, including its uri. Hosts 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.
• Define a cloud catalog and put each connection’s settings in its host block, including its AZ and network/storage bindings. Top-level libvirt blocks must be migrated into cloud hosts.
• 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.