Docs / Install

Installing KLYRN VM

Two roles, one binary. The controller is installed once; each compute node is enrolled from the controller with one command. Neither step asks a question it can answer itself, and both are resumable: an interrupted run picks up at the first stage that is not verified.

The controller

Any x86_64 Linux that runs systemd. The whole journey (install, first administrator, compute node, first machine built and reached) is run on a freshly reinstalled server for each system before a release is offered. As of 2026-10-09 it passes on Ubuntu 22.04, 24.04 and 26.04, Debian 12 and 13, AlmaLinux 8, 9 and 10, Rocky Linux 8, 9 and 10 and CentOS Stream 10. On Fedora 43 the controller installs and runs; Fedora is not accepted as a managed compute node.

curl -fsSL https://get.klyrn.com/vm | sudo bash

or, with a hostname the certificate should carry:

curl -fsSL https://get.klyrn.com/vm | sudo bash -s -- --hostname vm.example.com

One server for everything. A controller runs no machines by itself. With a single server, either install with

curl -fsSL https://get.klyrn.com/vm | sudo bash -s -- --single-server

or run klyrn-vm admin node add-local afterwards. Both make the controller's own server a compute node. The first compute node brings a private network (private, 10.100.0.0/24 behind the host's address), so a first machine can be created with nothing set up by hand. A provider running customers' machines should still keep the controller on a server of its own: one that is also a hypervisor loses both at once.

If SolusVM 2 is already running on this machine, the installer says so at the end, lists what it saw, and states that SolusVM is not stopped, not disabled, not reconfigured, and that its guests keep running. It does not offer to migrate anything: that decision belongs in the Migration Center, signed in, with the estate listed and a plan on screen, not in an installer running as root that may be answered by whoever happens to hold the terminal.

What it does, in order, and what each stage proves:

At the end it prints the URL and the setup token. Open the URL, accept the self-signed certificate, create the first administrator with the token.

klyrn-vm install --plan shows the stages and their state without changing anything. klyrn-vm doctor checks a running controller. As root:

setup-token is the one to know before it is needed. The installer prints the first-run token once; if that terminal is gone and no administrator has been created yet, this is how the controller is reached at all.

Ports: 8443 is for people and API clients; 8444 is for nodes only and requires a client certificate for everything except enrollment.

A compute node

In the controller: Compute nodes → Add node. Give it a name and a mode:

• observe for a host that another manager owns (a SolusVM node, a host you are evaluating). The agent reads libvirt, storage and networking and reports. It performs no mutation of any kind and installs no packages.
• managed for a host KLYRN VM will own. The agent installs QEMU/KVM, libvirt and the tools it needs, and creates its storage pool and networks.

A managed host must be one of:

Enterprise Linux is supported because that is what SolusVM estates run on, and a migration that cannot adopt the host it is migrating is not a migration. The version floors are checked rather than assumed: libvirt 5.2.0, below which every UEFI guest fails to define, and QEMU 4.0.0, below which discard is silently ignored and a thin disk grows to full size and never shrinks. Both are preflight failures with the consequence named.

Observe mode runs on any Linux and installs nothing at all.

Copy the one command shown and run it as root on the node:

curl -fsSL -k --pinnedpubkey sha256//… https://ctl:8444/node/v1/get-node.sh \
  | KLYRN_VM_CONTROLLER=https://ctl:8444 KLYRN_VM_TOKEN=klyrnvm_node_… \
    KLYRN_VM_CA=sha256:… bash -s -- --observe

Three parts of that line are per-installation and cannot be typed from here: the public-key pin, the token and the CA fingerprint. Copy it rather than transcribing it.

-k beside --pinnedpubkey is not a weakening. curl enforces the pin even with -k, so an untrusted chain is accepted and a substituted server is not, which is exactly what a controller whose certificate is still self-signed needs. Drop either flag and the command fails on TLS verification before it has fetched anything.

The script fetches the controller's CA, refuses to continue unless its fingerprint equals the one in the command, downloads the controller's own build over a connection verified by that CA, checks its SHA-256, and runs klyrn-vm node install. The token is one-time, expires in an hour, and is consumed the moment the node enrols. The node appears in the list as soon as it connects, with its facts and its readiness verdict.

A node can be promoted from observe to managed on its Settings tab. It never goes the other way silently: demoting is a deliberate act, and the node stops accepting changes the moment it learns of it.

What is where

Updates never touch /etc/klyrn-vm; a node keeps its identity across agent and controller updates.

This page is generated from the guide that ships in the product's repository, so it describes the release it was built from. What changed in each release.