Install

The CLI runs on Linux, macOS and Windows and needs Node 22 or newer. On Linux and macOS:

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

That is npm install -g @kvbox/cli with the prerequisites checked first. Run the npm command directly if you prefer, and on Windows:

npm install -g @kvbox/cli

Rerun either to upgrade. kvbox --version prints what you have.

Log inCopy Anchor Link

kvbox login
kvbox whoami

kvbox login asks for the email and password of your account on api.kvbox.sh (or pass the URL of your own control plane: kvbox login https://cp.example.com). It stores a token under ~/.kvbox/cli.json and uploads the SSH key it generates under ~/.kvbox/ssh, so new boxes let you in. From then on every command talks to the control plane. kvbox logout goes back to the server on this machine, and --local does that for one command.

For scripts, kvbox login -e you@example.com --password-stdin reads the password from stdin.

Running boxes on your own machineCopy Anchor Link

The CLI alone runs nothing. Boxes run on a host: a Linux machine with KVM that runs kvbox-server. Install a server on one, or log in and use hosts that joined a control plane.