Installation

VM Registry runs on any Linux system with KVM/libvirt support. The fastest path is the install script; per-distro steps and Nix options are also covered below.

Quick Install (Script)

A single command installs the CLI (vmr), daemon, and desktop app:

curl -fsSL https://vm-registry.com/install.sh | sh
sudo usermod -aG kvm,libvirt $USER
systemctl --user enable --now vm-registry-daemon

Re-login (or run newgrp kvm) for group membership to take effect, then verify:

vmr --version

Script options

Flag	Description
--no-deps	Skip automatic libvirt/qemu installation
--no-desktop	Skip vm-registry-desktop installation

# install CLI + daemon only, skip desktop and system deps
curl -fsSL https://vm-registry.com/install.sh | sh -s -- --no-deps --no-desktop

---

Per-distro

Debian / Ubuntu

# 1. system dependencies
sudo apt-get install -y libvirt-daemon-system qemu-kvm qemu-utils libvirt-clients
sudo systemctl enable --now libvirtd

# 2. CLI and daemon via install script (skip dep step)
curl -fsSL https://vm-registry.com/install.sh | sh -s -- --no-deps

# 3. permissions and service
sudo usermod -aG kvm,libvirt $USER
systemctl --user enable --now vm-registry-daemon

Fedora / RHEL / AlmaLinux

sudo dnf install -y libvirt qemu-kvm libvirt-client
sudo systemctl enable --now libvirtd

curl -fsSL https://vm-registry.com/install.sh | sh -s -- --no-deps

sudo usermod -aG kvm,libvirt $USER
systemctl --user enable --now vm-registry-daemon

Arch Linux

sudo pacman -Sy libvirt qemu-desktop
sudo systemctl enable --now libvirtd

curl -fsSL https://vm-registry.com/install.sh | sh -s -- --no-deps

sudo usermod -aG kvm,libvirt $USER
systemctl --user enable --now vm-registry-daemon

openSUSE

sudo zypper install -y libvirt qemu-kvm libvirt-client
sudo systemctl enable --now libvirtd

curl -fsSL https://vm-registry.com/install.sh | sh -s -- --no-deps

sudo usermod -aG kvm,libvirt $USER
systemctl --user enable --now vm-registry-daemon

---

Nix / NixOS

Nix profile (any Linux or macOS)

nix profile install github:VM-Registry/vm-registry#vm-registry-cli
nix profile install github:VM-Registry/vm-registry#vm-registry-daemon
systemctl --user enable --now vm-registry-daemon

Install the desktop app:

nix profile install github:VM-Registry/vm-registry#vm-registry-desktop

NixOS module

The daemon ships a NixOS module re-exported from the monorepo flake:

{
  inputs.vm-registry.url = "github:VM-Registry/vm-registry";

  outputs = { vm-registry, nixpkgs, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      modules = [
        vm-registry.nixosModules.default
        {
          services.vm-registry-daemon.enable = true;
        }
      ];
    };
  };
}

nix-shell / nix run (one-off)

# run the CLI without installing
nix run github:VM-Registry/vm-registry#vm-registry-cli -- --version

# temporary shell with vmr on PATH
nix-shell -p 'let f = builtins.getFlake "github:VM-Registry/vm-registry"; in f.packages.x86_64-linux.vm-registry-cli'

---

Manual install (from source)

CLI (Rust)

git clone https://github.com/VM-Registry/cli
cd cli
cargo build --release
sudo install -m 755 target/release/vmr /usr/local/bin/vmr

Daemon (Go)

git clone https://github.com/VM-Registry/daemon
cd daemon
go build -o vm-registry-daemon ./server/main.go
sudo install -m 755 vm-registry-daemon /usr/local/bin/vm-registry-daemon

Install the systemd user service:

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/vm-registry-daemon.service <<'EOF'
[Unit]
Description=VM Registry Daemon
After=network.target

[Service]
ExecStart=/usr/local/bin/vm-registry-daemon
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now vm-registry-daemon

Desktop (Tauri)

git clone https://github.com/VM-Registry/desktop
cd desktop
# requires Node.js, Rust, and Tauri CLI
cargo tauri build

---

Desktop app

The desktop app (vm-registry-desktop) is a GUI frontend for managing VMs locally. It connects to the daemon over the Unix socket.

GitHub Releases provide pre-built binaries for:

Format	Distros
.deb	Debian, Ubuntu, and derivatives
.rpm	Fedora, RHEL, AlmaLinux, openSUSE
.AppImage	Any Linux (portable, no install)

Download from the vm-registry-desktop releases page or use the install script.

---

Daemon configuration

The daemon reads configuration from flags or environment variables:

Flag	Env	Default	Description
-socket	VM_REGISTRY_SOCKET_PATH	/var/run/vm-registry.sock	Unix socket path
-registry-url	VM_REGISTRY_SERVER_URL	—	Registry server URL
-auth-url	VM_AUTH_SERVER_URL	—	Auth server URL
-storage	—	filesystem	Storage backend (filesystem or s3)
-fs-path	VM_REGISTRY_STORAGE_PATH	/var/lib/vm-registry	Local storage path
-log-level	VM_REGISTRY_LOG_LEVEL	info	Log verbosity

Override via the systemd service drop-in:

mkdir -p ~/.config/systemd/user/vm-registry-daemon.service.d
cat > ~/.config/systemd/user/vm-registry-daemon.service.d/override.conf <<'EOF'
[Service]
Environment=VM_REGISTRY_SERVER_URL=https://registry.example.com
Environment=VM_AUTH_SERVER_URL=https://auth.example.com
EOF
systemctl --user daemon-reload
systemctl --user restart vm-registry-daemon

---

Prerequisites

• Linux kernel with KVM support (lsmod | grep kvm)
• libvirt ≥ 7.0 with QEMU/KVM driver
• CPU with hardware virtualisation (Intel VT-x or AMD-V)

Verify KVM is available:

grep -Ec '(vmx|svm)' /proc/cpuinfo   # > 0 means supported
ls /dev/kvm                           # must exist