Quickstart

This is the flow Kubrain is built for: hand it a directory of code, and get back a running service on a URL. Every step is one tool call — shown here as MCP tool names, with the equivalent CLI verb alongside.

Kubrain is driven by an agent. In practice you ask (“ship this app and put it on app.example.com”) and the agent runs the steps below. They’re spelled out so you know what it’s doing — and so you can script the same flow in CI with the CLI.

Install the CLI

Grab a static binary from the latest release — Linux, macOS, and Windows, amd64 and arm64, no dependencies.

# Linux / macOS — pick your os/arch: linux_amd64 · linux_arm64 · darwin_amd64 · darwin_arm64
curl -fsSL -o kubrain \
  https://github.com/kubrain-dev/kubrain-cli/releases/latest/download/kubrain_linux_amd64
chmod +x kubrain && sudo mv kubrain /usr/local/bin/kubrain
kubrain --version

On Windows, download kubrain_windows_amd64.exe (or _arm64), rename it to kubrain.exe, and add it to your PATH. Verify any download against the release’s checksums.txt with sha256sum -c checksums.txt.

0 · Sign up & connect

Create an account either way — on the website at kubrain.dev, or straight from the CLI:

kubrain auth signup --email you@example.com   # register from the terminal (prompts for a password)
kubrain auth login  --email you@example.com   # already have an account
kubrain quota                                 # sanity check: your limits and €/month view

Either path stores a tenant Bearer token in ~/.kubrain/config. To drive Kubrain from Claude, add that same token — with the remote MCP server URL — to your agent’s config.

pricing, estimate, versions, and regions need no token — use them to plan before you sign up.

1 · Understand the code

detect <dir>            # CLI: kubrain deploy detect <dir>

Reports language, package manager, entrypoint, ports, and whether a Dockerfile, kubrain.yaml, or kubrain/k8s-templates/ already exist.

2 · Make it buildable

If there is no kubrain.yaml (and/or no Dockerfile):

scaffold <dir>          # CLI: kubrain deploy scaffold <dir>

writes sensible defaults you then tailor — see the kubrain.yaml reference. A Dockerfile is the most predictable build; without one the cloud builder falls back to buildpacks.

3 · Prove it renders

validate <dir>          # CLI: kubrain deploy validate <dir>

runs the exact build ladder and template engine the cloud uses, so “valid locally” ≡ “will build in the cloud.” To see the Kubernetes objects it will produce, kubrain deploy render --dir <dir>.

4 · Ensure a cluster exists

list_clusters

If there is nowhere to deploy, provision one — always estimate the cost first:

estimate  tier=ha ram=8 nodes=2          # returns €/hour and €/month
create_cluster <name> tier=ha ram=8 nodes=2 k8s=<version>   # dry_run first

create_cluster defaults to dry_run in MCP — it returns the full plan (node IPs, public endpoint, cost) and applies nothing. Run it for real, then poll:

get_cluster <name>                       # until state = running

Pick a version with versions, a region/zone with regions, and check headroom with get_quota. Tiers: dev (1 schedulable control plane, prototypes), normal (1 dedicated control plane + workers), ha (3 control planes, for production).

5 · Add the web-facing add-ons

For anything served over HTTP(S), make sure the cluster has an ingress controller and TLS:

install_addon <cluster> ingress-nginx                       # +€3.50/mo for the LB IP
install_addon <cluster> cert-manager issuer_email=you@example.com   # free TLS

Both are idempotent. list_addons shows the catalogue and what’s installed.

6 · Register the deployment

create_deployment <name> cluster=<cluster>

establishes a stable handle; the name becomes the namespace kbn-<name>. Add repo/branch to bind Git for auto-builds (retrieve the deploy key to add to your repo with get_deploy_key <name>).

7 · Supply secrets (if any)

set_secret <name> <KEY> --value-file <path>    # value read from a file, never inline

Every managed key is exposed to the workload as an env var automatically.

8 · Ship it

deploy <name> dir=<path>        # CLI: kubrain deploy ship <name> --dir <path>

builds from your local source in the cloud and rolls it out (or pass image=<ref> for a prebuilt image). Then poll:

get_deployment <name>           # until the release is live

9 · Put it on the internet

If your kubrain.yaml declares an ingress, the rollout already created the Ingress and requested TLS. Point DNS at the cluster’s ingress IP:

create_zone example.com                        # if new; delegate the NS at your registrar
set_record example.com app A <ingress-ip>

Find the ingress IP from kubectl --kubeconfig <file> get svc -n ingress-nginx (its EXTERNAL-IP). cert-manager issues the certificate within a minute or two.

10 · You’re live

Report the URL, the release id, and the monthly cost. From here:

Deploy an app — releases, triggers, promote/rollback.
Metrics — get_metrics gives golden signals with zero instrumentation.
Alerting — page yourself on errors, latency, pod health, or an ingress going down.

Overview Core concepts