Run your own kvbox host on a Linux machine

kvbox is a Firecracker microVM manager, and the part that runs the VMs is just a program on a Linux machine. If you have a server with KVM, you can be that provider yourself: no account, nothing listening on the network until you decide it should.

A host on its own is a complete kvbox. This post walks through what it takes to set one up and what the installer does on your machine, so there are no surprises.

What you need

• A Linux machine with KVM: /dev/kvm has to exist, so virtualization must be on in the BIOS, and a cloud VM needs nested virtualization.
• x86_64. Firecracker also runs on aarch64, but the guest kernel is only built for x86_64 so far, and the installer stops there.
• Node.js 22.13 or newer, and curl, tar, sha256sum, zstd and the e2fsprogs tools.
• Your own user. The installer refuses to run as root, because the state directory lives in your home.

Boxes want RAM more than anything: a box holds its memory while it runs or is paused. Rented bare metal with a lot of memory is the natural home for a host, but a spare machine at home works as well.

One script

$ curl -fsSL https://kvbox.sh/install-server.sh | bash

It checks the prerequisites first and fails early with a message that says what to fix. Then it asks once whether to continue, and works through these steps:

• Firecracker, pinned to one release and verified against its published checksum, together with the jailer and snapshot editor.
• The guest kernel and base image, a Linux 6.1 build for kvbox and an Ubuntu 24.04 root filesystem. Both are checksummed too. Every box shares the image read-only and keeps only the blocks it changes.
• The packages: @kvbox/server, the daemon, and @kvbox/cli, the command you type.
• An SSH key that kvbox connect uses to get into your boxes.
• KVM access: it adds you to the group that owns /dev/kvm.
• Host networking: a bridge called kvbox0 on 172.30.0.0/24, with NAT out through the default route.
• A systemd service so the server starts at boot.

Almost all of that runs as you, in ~/.kvbox. It asks for sudo only where root is required: the group change, the bridge and firewall rules, the systemd unit, and a sudoers rule that lets the server run one root-owned networking helper without a password. That rule covers exactly that file, nothing broader.

KVBOX_YES=1 takes every default and asks nothing, which is what you want in a provisioning script.

Start your first box

Log out and back in once so the new group applies, or run newgrp kvm in the current shell. Then:

$ kvbox server status
$ kvbox new lab1
$ kvbox connect lab1

The server listens on a Unix socket under ~/.kvbox, so on the host the CLI talks to it directly. Nothing is open to the network.

If the machine reboots, the service starts again and brings back every box that was running. A paused box lost its memory with the host and stays stopped, and a hibernated one stays hibernated.

Where things live

Everything is under ~/.kvbox, or wherever KVBOX_HOME points: boxes as machines/<owner>/<name>, snapshots as snapshots/<owner>/<name>, and a small ledger of usage. There is no hidden database. The files are the state, and each one is validated when it is read.

That makes backing up a host a matter of copying a directory, and debugging one a matter of reading it.

Reaching it from elsewhere

A host alone is enough while you sit at the machine. To reach your boxes from your laptop, or to run several hosts as one, put the host behind a control plane. An admin creates a one-time token, and you run one command on the host:

$ kvbox server join https://api.kvbox.sh --token <token>

The host makes a TLS certificate, tells the control plane where it can be reached, and from then on answers on port 7777 to that control plane only. Each box also gets its own public SSH port on the host.

A host behind a home router

A machine at home has no public address for any of that to reach. kvbox has a small relay for exactly this: a cheap public VM with spare IPv4 addresses lends one to each host over a WireGuard tunnel.

$ kvbox-relay add home1 --ip <extra-public-ip>

That runs on the relay VM and prints one line. On the home host you paste it:

$ kvbox server relay <the line it printed>

The host brings the tunnel up, and again after a reboot, and advertises the lent address when it joins a control plane. There is nothing to open on the router.

Try it

A host takes a few minutes, mostly downloads. The install guide in the docs has the full reference, and the relay guide covers the home-router case in detail.