Join a control plane

A host alone is complete, but the CLI has to be on it. A control plane (api.kvbox.sh, or your own) lets you log in from anywhere, places new boxes on the host with the most room, and lets several hosts show up as one. See Install for logging in.

An admin on the control plane mints a one-time token for the host; you run its command on the host:

kvbox server join https://api.kvbox.sh --token <token> [--advertise <public host or ip>] [--name <name>]
kvbox server leave       # forget the control plane; the port closes

Both restart the server for you (running boxes are not affected).

What join doesCopy Anchor Link

• makes the host's TLS certificate under ~/.kvbox/tls; the control plane pins its fingerprint
• sends the address the control plane reaches the host at: the default-route address, or --advertise (a private address has to be named explicitly)
• keeps the secret it gets back in config.json

From its next start the server also answers on HTTPS port 7777, to that control plane only: every call has to carry the secret. The control plane's users become owners <user>@<control plane> on the host, kept apart from the host owner's own boxes. Each box also gets its own public SSH port on the host, which kvbox connect uses from outside.

Every 30 seconds the control plane polls its hosts: a host that does not answer within two seconds shows its boxes in ls with status unknown rather than hiding them, and its usage ledger is pulled in the same sweep.