Getting Started

kcl (Kubernetes Cluster Launcher) creates a ready-to-use Kubernetes cluster on a VPS — either one it provisions for you, or one you already have.

Install CLI

curl -sfL https://get.kcl.wolke.host | sh

Create a Cluster

There are two ways to create a cluster, depending on whether you want kcl to provision the server for you or you already have one.

Option A: Let kcl provision a server

kcl creates the VPS, installs Kubernetes, and bootstraps it in one step. Requires the HCLOUD_TOKEN environment variable, set to a valid Hetzner Cloud API token.

export HCLOUD_TOKEN=your-hetzner-api-token
kcl create hello --provider=hetzner

--provider stringCloud provider to use (currently: hetzner)
--image stringOS image (default "ubuntu-24.04")
--size stringInstance size/type (default "cx23")
--region stringRegion or location (default "nbg1")

Option B: Use your own existing server

kcl create hello --host=IP_or_hostname --user=username --key=path/to/key

--host stringVPS IP address or hostname
--user stringSSH user (default "root")
--key stringPath to SSH private key
--password stringSSH password (only needed the first time, if kcl's key isn't already on the server)

If you don't pass --key, kcl generates one for you at ~/.kcl/ssh/<cluster-name>/id_ed25519 and installs it on the server automatically.

--provider and --host can't be used together — pick one.

Note: make sure ports 80, 443, and 6443 are open to inbound traffic (firewall / security group) — kcl needs them for HTTP/HTTPS ingress and the Kubernetes API server.

What happens next

Once the node is reachable, kcl installs Kubernetes and automatically sets up ingress-nginx, cert-manager, and Let's Encrypt, so your cluster can serve HTTPS traffic right away.

Use your cluster

kcl use hello
kubectl get nodes

Providers

Currently supported for --provider:

hetzner

CLI Reference

kcl create <name>

Creates a new cluster, either on a provider-hosted VPS or your own server. See Create a Cluster above for a walkthrough.

--provider stringCloud provider to use (currently: hetzner). Requires HCLOUD_TOKEN. Cannot be used with --host
--image stringOS image, used with --provider (default "ubuntu-24.04")
--size stringInstance size/type, used with --provider (default "cx23")
--region stringRegion or location, used with --provider (default "nbg1")
--host stringVPS IP address. Cannot be used with --provider
--user stringSSH user, used with --host (default "root")
--key stringPath to SSH private key, used with --host (auto-generated if omitted)
--password stringSSH password, used with --host (only needed the first time)

kcl list

Lists every cluster kcl is currently managing, along with its host address.

kcl list

No flags.

kcl status <cluster-name>

Shows a live dashboard for a cluster: SSH connectivity, control plane status (version, role, API server health), and current RAM/CPU usage on the node.

kcl status hello

No flags. Takes one positional argument, the cluster name.

kcl use <cluster-name>

Merges the cluster's kubeconfig into your default kubeconfig and switches your active kubectl context to it.

kcl use hello

No flags. Takes one positional argument, the cluster name.

kcl sans add <cluster-name> <ip-or-domain>

Adds a trusted IP address or domain name to the cluster's API server certificate, so you can connect to kubectl using that address without a certificate error.

:
kcl sans add hello api.example.com

No flags. Takes two positional arguments: cluster name, then the IP address or domain to trust.

kcl detects your node's Kubernetes distribution (k0s, k3s, or kubeadm) automatically and restarts the control plane to apply the change. You may be prompted for the server's sudo password. Allow ~15 seconds after it finishes before running kubectl commands again.