Commands: kvbox

Global options, accepted before any command:

Option	What it does
`--local`	use this machine's kvbox-server over its socket, ignoring kvbox login
`--org <slug>`	the org: where kvbox new creates, and which box a name means when it is not one of yours; before the command here, or after it

kvbox login [url] [options]

Argument	Meaning
`[url]`	control plane URL (default: https://api.kvbox.sh)

Option	What it does
`-e, --email <email>`	account email (prompted otherwise)
`--password-stdin`	read the password from the first line of stdin (for scripts)

kvbox logout

log out of the control plane; commands target this machine's kvbox-server again

kvbox logout

kvbox org

orgs: shared slugs that own boxes, with owners, admins and members

kvbox org

kvbox org ls

list the orgs you belong to and your role in each

kvbox org ls [options]

Option	What it does
`--json`	print as JSON

kvbox org members

who is in an org and what they may do

kvbox org members

kvbox org members add

add a user to an org (admins and owners; only an owner can add an owner)

kvbox org members add <user> [options]

Argument	Meaning
`<user>`	their username

Option	What it does
`-r, --role <role>`	their role (default: `member`)
`-o, --org <slug>`	the org (or --org before the command)

kvbox org members ls

list an org's members and their roles

kvbox org members ls [options]

Option	What it does
`-o, --org <slug>`	the org (or --org before the command)
`--json`	print as JSON

kvbox org members rm

remove a member (or leave: remove yourself)

kvbox org members rm <user> [options]

Argument	Meaning
`<user>`	their username

Option	What it does
`-o, --org <slug>`	the org (or --org before the command)
`-y, --yes`	do not ask for confirmation

kvbox org new

create an org; you become its owner (the slug is permanent, the name is not)

kvbox org new <slug> [options]

Argument	Meaning
`<slug>`	the org's slug: lowercase, like a username (acme)

Option	What it does
`-n, --name <name>`	display name (default: the slug)
`--json`	print the org as JSON

kvbox org rm

delete an org (owners only; remove its boxes and snapshots first)

kvbox org rm <slug> [options]

Argument	Meaning
`<slug>`	the org

Option	What it does
`-y, --yes`	do not ask for confirmation

kvbox org role

change a member's role (owners only)

kvbox org role <user> <role> [options]

Argument	Meaning
`<user>`	their username
`<role>`	owner, admin or member

Option	What it does
`-o, --org <slug>`	the org (default: the current context)

kvbox server

run or manage the kvbox server

kvbox server

kvbox server join

put this machine behind a control plane (needs a one-time token minted there) and restart its server

kvbox server join <control-plane-url> [options]

Argument	Meaning
`<control-plane-url>`	the control plane, e.g. https://api.kvbox.sh

Option	What it does
`--token <token>`	one-time join token from the control plane
`--advertise <host-or-ip>`	address the control plane reaches this machine at (default: its default-route address)
`--name <name>`	how the control plane lists this machine (default: hostname)

kvbox server leave

take this machine out from behind its control plane and restart its server

kvbox server leave

kvbox server relay

reach the internet through a relay (paste what kvbox-relay add printed on the relay VM); off takes the tunnel down

kvbox server relay <join-string>

Argument	Meaning
`<join-string>`	the line `kvbox-relay add` printed, or `off`

kvbox server start

start the local kvbox-server in the background

kvbox server start

kvbox server status

show whether this machine's server is running, its control plane and which base image new boxes get

kvbox server status [options]

Option	What it does
`--json`	print as JSON

kvbox server stop

stop the local server (running boxes are not affected)

kvbox server stop

kvbox server trust-ca

make every cloud box on this machine trust a new SSH CA (after ca rotate on the control plane)

kvbox server trust-ca [public-key] [options]

Argument	Meaning
`[public-key]`	the CA public key (or its cert-authority line); or --from-cloud

Option	What it does
`--from-cloud`	ask the control plane this host joined for its current CA, show the fingerprint, then ask
`-y, --yes`	do not ask for confirmation
`--json`	print the report as JSON

kvbox snapshots

freeze running boxes into snapshots and manage them

kvbox snapshots

kvbox snapshots ls

list snapshots (yours and your orgs'; --org <slug> for one org)

kvbox snapshots ls [options]

Option	What it does
`-a, --all`	kept for older scripts: the listing covers everything you can see anyway
`--json`	print as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox snapshots new

freeze a running box (memory + disk) into a snapshot; the box keeps running

kvbox snapshots new <box> <name> [options]

Argument	Meaning
`<box>`	box name
`<name>`	snapshot name

Option	What it does
`--json`	print the snapshot as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox snapshots rm

delete a snapshot (boxes made from it are not affected)

kvbox snapshots rm <name> [options]

Argument	Meaning
`<name>`	snapshot name

Option	What it does
`-y, --yes`	do not ask for confirmation
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm

manage boxes (each one is a Firecracker microVM)

kvbox vm

kvbox vm connect

Shortcut: kvbox connect.

open a shell in a box over SSH (or run a command: kvbox connect <name> -- <cmd>)

kvbox vm connect <name> [cmd] [options]

Argument	Meaning
`<name>`	box name
`[cmd]`	command to run instead of a shell

Option	What it does
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm exec

Shortcut: kvbox exec.

run a command in a box and exit with its status (kvbox exec <name> -- <cmd>)

kvbox vm exec <name> <cmd> [options]

Argument	Meaning
`<name>`	box name
`<cmd>`	command, passed to the box's shell as one string (pipes, &&, cd work)

Option	What it does
`-e, --env <KEY=VALUE>`	set an environment variable for the command (repeatable)
`--timeout <seconds>`	kill the command after N seconds and exit 124
`--tty`	allocate a pseudo-terminal (for interactive tools like htop)
`--json`	capture output and print {"output": "...", "exit_code": N}
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm hibernate

Shortcut: kvbox hibernate.

save a box's memory to disk and free its RAM (kvbox wake continues it where it left off)

kvbox vm hibernate <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`--json`	print the box as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm ls

Shortcut: kvbox ls.

list boxes with status and address (yours and your orgs'; --org <slug> for one org)

kvbox vm ls [options]

Option	What it does
`-a, --all`	kept for older scripts: the listing covers everything you can see anyway
`--json`	print as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm new

Shortcut: kvbox new.

boot a new box from the base image or a snapshot

kvbox vm new [name] [options]

Argument	Meaning
`[name]`	box name (box1, box2, … when omitted)

Option	What it does
`-s, --size <size>`	box size (default: server config, s)
`-f, --from <snapshot>`	start from a snapshot instead of the base image
`--force`	skip the capacity guard
`--json`	print the box as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm pause

Shortcut: kvbox pause.

freeze a box in place (memory and processes kept, no CPU used; kvbox resume continues it instantly)

kvbox vm pause <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`--json`	print the box as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm rescale

change a box's vCPUs, memory or disk (e.g. --vcpu 4 --mem 16GB); a running box restarts

kvbox vm rescale <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`-s, --size <size>`	a preset to start from
`--vcpu <n>`	number of vCPUs
`--mem <size>`	memory, e.g. 16GB or 4096MB
`--disk <size>`	disk size, e.g. 32GB (grow only)
`--json`	print the box as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm resume

Shortcut: kvbox resume.

continue a box that is in standby (kvbox pause)

kvbox vm resume <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`--json`	print the box as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm rm

Shortcut: kvbox rm.

destroy a box (its disk is deleted; snapshots are kept)

kvbox vm rm <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`-y, --yes`	do not ask for confirmation
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm start

Shortcut: kvbox start.

boot a stopped box again (same name, IP and disk)

kvbox vm start <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`--json`	print the box as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm stop

Shortcut: kvbox stop.

shut a box down (its disk is kept; start it again with kvbox start)

kvbox vm stop <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`--json`	print the box as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm update

move a box onto the current base image (its files stay; a running box restarts)

kvbox vm update <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`--json`	print the box as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm usage

how long a box ran, slept and sat stopped, as vCPU-hours, RAM and disk GiB-hours (and cost, when the host prices them)

kvbox vm usage <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`--since <date>`	count from this date instead of the box's creation, e.g. 2026-10-01
`--json`	print as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox vm wake

Shortcut: kvbox wake.

continue a hibernated box where it left off (same name, IP and disk)

kvbox vm wake <name> [options]

Argument	Meaning
`<name>`	box name

Option	What it does
`--json`	print the box as JSON
`--org <slug>`	act in this org (- for your personal boxes)

kvbox whoami

show which account and control plane commands target (or local mode)

kvbox whoami [options]

Option	What it does
`--json`	print as JSON

Commands

kvbox loginCopy Anchor Link

kvbox logoutCopy Anchor Link

kvbox orgCopy Anchor Link

kvbox org lsCopy Anchor Link

kvbox org membersCopy Anchor Link

kvbox org members addCopy Anchor Link

kvbox org members lsCopy Anchor Link

kvbox org members rmCopy Anchor Link

kvbox org newCopy Anchor Link

kvbox org rmCopy Anchor Link

kvbox org roleCopy Anchor Link

kvbox serverCopy Anchor Link

kvbox server joinCopy Anchor Link

kvbox server leaveCopy Anchor Link

kvbox server relayCopy Anchor Link

kvbox server startCopy Anchor Link

kvbox server statusCopy Anchor Link

kvbox server stopCopy Anchor Link

kvbox server trust-caCopy Anchor Link

kvbox snapshotsCopy Anchor Link

kvbox snapshots lsCopy Anchor Link

kvbox snapshots newCopy Anchor Link

kvbox snapshots rmCopy Anchor Link

kvbox vmCopy Anchor Link

kvbox vm connectCopy Anchor Link

kvbox vm execCopy Anchor Link

kvbox vm hibernateCopy Anchor Link

kvbox vm lsCopy Anchor Link

kvbox vm newCopy Anchor Link

kvbox vm pauseCopy Anchor Link

kvbox vm rescaleCopy Anchor Link

kvbox vm resumeCopy Anchor Link

kvbox vm rmCopy Anchor Link

kvbox vm startCopy Anchor Link

kvbox vm stopCopy Anchor Link

kvbox vm updateCopy Anchor Link

kvbox vm usageCopy Anchor Link

kvbox vm wakeCopy Anchor Link

kvbox whoamiCopy Anchor Link

On this page

kvbox login