Install nsl¶

nsl is a single binary that runs as your user. You'll need an x86-64 Linux host with KVM to run the x86-64 VM and machine images. Releases also include a linux_arm64 CLI binary, but it cannot run machines: create rejects non-x86-64 hosts. The tested setup is Snow Linux 13 with systemd 261.2, QEMU 10.0.13, virtiofsd 1.13.2 and GNOME Wayland.

Host requirements¶

Requirement	Used for
systemd 259 or newer: `systemd-vmspawn`, `systemd-run`, `systemctl` and a user systemd manager	Running each VM as a user unit
QEMU (`qemu-system-x86_64`) with KVM	The VM
UEFI firmware without Secure Boot, with a QEMU firmware descriptor (`ovmf`, or Fedora's `edk2-ovmf`)	Booting the VM
virtiofsd at `/usr/libexec/virtiofsd`	Sharing your files and the image cache with the VM
OpenSSH (`ssh`, `ssh-keygen`) and `/usr/lib/systemd/systemd-ssh-proxy`	Reaching the VM's agent over vsock
`sg` or util-linux `newgrp` (on Debian 14, both from `util-linux-extra`), and util-linux `unshare`	Opening the KVM devices through your `kvm` membership
`getent` and `id`	Checking `kvm` membership in the host account database
Membership in `kvm`, with access to `/dev/kvm` and `/dev/vhost-vsock`	Hardware virtualization and vsock
Unprivileged user namespaces	Launching the VM without root
Waypipe (optional)	Wayland windows from machines

Run nsl doctor to find out which prerequisites you're missing. Install them with your host's own tools. nsl doesn't install host packages or change device permissions, groups or sudoers.

Install with Homebrew¶

On Linux with Homebrew ↗, install the CLI from the Frostyard tap ↗. Add the tap first, then install the cask:

brew tap frostyard/tap
brew install --cask frostyard/tap/nsl
nsl doctor

The cask installs only the CLI; the host requirements above still apply. VM and machine images are downloaded and verified when you create a machine.

To update the CLI:

brew update
brew upgrade --cask frostyard/tap/nsl

Download a release¶

Each release has tarballs for linux_amd64 and linux_arm64, a checksums.txt, and GitHub build provenance. The files have the same names in every release, so these steps always fetch the newest one. Use linux_amd64 on the supported x86-64 hosts, as below.

Download the tarball and the checksums from the latest release ↗:

base=https://github.com/frostyard/nsl/releases/latest/download
curl -LO "$base/nsl_linux_amd64.tar.gz" -LO "$base/checksums.txt"

To pin a release instead, set base to https://github.com/frostyard/nsl/releases/download/vVERSION.

Check the tarball against the checksums, and its provenance with the GitHub CLI:

sha256sum --ignore-missing -c checksums.txt
gh attestation verify nsl_linux_amd64.tar.gz --repo frostyard/nsl

Unpack the binary somewhere on your PATH, and check which release you have:

tar -xzf nsl_linux_amd64.tar.gz nsl
mkdir -p ~/.local/bin
install -m 0755 nsl ~/.local/bin/nsl
nsl version

Build from source¶

To build it yourself, use Go 1.27.4 or newer.

git clone https://github.com/frostyard/nsl.git
cd nsl
make build   # writes build/nsl

Check the host¶

nsl doctor

A passing check looks like this (one line of the full output):

OK kvm group membership

For a MISSING result, follow troubleshooting.

doctor prints OK or MISSING for each tool, for the systemd version and for the UEFI firmware systemd-vmspawn would use. Fedora 44 and Ubuntu 26.04 LTS ship systemd 259; Debian 13 ships 257, which is too old. It checks device access in your current session, looks up your kvm membership in the host account database, then tries KVM and vsock access through that group. It also checks user namespaces and the user systemd manager. A missing VM prerequisite makes it exit with an error.

Having firmware installed isn't enough on its own. systemd-vmspawn needs a QEMU firmware descriptor in /usr/share/qemu/firmware or /etc/qemu/firmware; without one, doctor reports the firmware as missing. Waypipe is optional, but you'll need it to display machine windows on the host.

If you aren't a member of kvm, doctor and VM launch report the missing membership with a command such as sudo usermod -aG kvm 'YOUR_USERNAME' for an administrator to run. They skip the group switch so it cannot ask for a group password. Once membership is added, retry nsl; no new login is needed. Device permissions must still allow the kvm group access.

Next, create your first machine.

Uninstall¶

Run nsl shutdown before removing the CLI. For Homebrew, run brew uninstall --cask frostyard/tap/nsl. For the tarball installation above, remove ~/.local/bin/nsl; if you installed it elsewhere, remove that binary instead. You can also delete the downloaded tarball, checksums and unpacked copy.

Both methods leave your machines and state in NSL_HOME, along with your separate nsl.conf settings. See where state lives. To delete machines too, remove them with nsl before uninstalling.