Install a server

A host is a Linux machine with KVM that runs kvbox-server: it owns Firecracker, the boxes and their networking, and serves the API the CLI uses. Node 22.13 or newer must be present.

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

It installs a pinned Firecracker, the guest kernel, the base image, the SSH key kvbox connect uses, both npm packages (@kvbox/cli and @kvbox/server), and adds you to the kvm group; it asks for sudo only where root is needed (the bridge, NAT and firewall rules). Rerun it any time, it only changes what is missing, and it is how a host is upgraded. KVBOX_YES=1 takes every default.

After the first install, log in again (or newgrp kvm) so the group change applies before the first kvbox new.

The serverCopy Anchor Link

kvbox server start
kvbox server status
kvbox server stop        # running boxes are not affected

The server listens on a Unix socket under ~/.kvbox, so a host alone is a complete kvbox: nothing listens on the network. On the host the CLI talks to it directly (kvbox --local if you are also logged in to a control plane).

State lives under ~/.kvbox (KVBOX_HOME to move it): boxes as machines/<owner>/<name>, snapshots as snapshots/<owner>/<name>, the ledger in kvbox.db. The filesystem is the database; every file there is validated when read.

HardwareCopy Anchor Link

Boxes want RAM more than anything: a box holds its RAM while running or paused. Rented bare metal with a lot of memory is the natural home for a host. A machine at home behind a router works too, with a relay for a public address.