Install docs

Get Berth running

Berth ships as a single container (or a single binary). Pick the way that fits you, all three end with the dashboard on http://localhost:8081. No prior Berth knowledge needed.

How it works

Berth is one process: a web UI baked into a small Go binary that talks to the Kubernetes API. It runs in one of two modes:

remotecluster, talks to a cluster using your local ~/.kube/config. Best for trying it on your laptop (the binary and Docker methods).
incluster, runs as a pod and uses its ServiceAccount. This is what the Helm chart deploys.

Viewing is always free, no key needed. A license key only unlocks changes (create/edit/delete). Grab a free Community key any time from your account, see Apply your key.

Prerequisites

A Kubernetes cluster you can reach. Anything works, a cloud cluster, or local kind/minikube/k3d.
kubectl configured for it. Check with kubectl get nodes, if that lists nodes, you're set.
For the Helm method: Helm 3.8+. For Docker: any recent Docker/Podman.
Optional: metrics-server for CPU/memory graphs. Berth degrades gracefully without it.

1 · Run the binary

The fastest way to look at a cluster. One self-contained file, no installer, uses your kubeconfig.

Install and verify. Pick your operating system, then copy-paste the script. It downloads the build, checks its signature, and installs berth onto your PATH.

export AUTH_TOKEN="$(openssl rand -hex 32)"
curl -sSLO https://github.com/unishsys/berth/releases/download/v0.4.1/berth-linux-amd64
curl -sSLO https://github.com/unishsys/berth/releases/download/v0.4.1/SHA256SUMS
shasum -a 256 -c SHA256SUMS --ignore-missing   # optional integrity check
chmod +x berth-linux-amd64
sudo mv berth-linux-amd64 /usr/local/bin/berth

On ARM64 hardware, swap berth-linux-amd64 for berth-linux-arm64 in both lines that reference it.

Run it against your current kubeconfig context, then open the dashboard. berth is on your PATH now, so this is the same on every OS:

berth remotecluster
# now open http://localhost:8081

Local mode binds to loopback and requires a token of at least 32 characters. Paste the AUTH_TOKEN generated in step 1 into the dashboard when prompted. The token is kept in this tab’s session storage when available. Closing the tab clears it; blocked storage also clears it on reload.

2 · Run with Docker

Same as the binary, but containerized, mount your kubeconfig read-only and Berth uses it.

Run the signed image with your kubeconfig mounted at the location the nonroot user expects:

export AUTH_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8081:8081 \
  -e AUTH_TOKEN -e AUTH_MODE=token -e BIND_ADDRESS=0.0.0.0 \
  -v "$HOME/.kube/config:/home/nonroot/.kube/config:ro" \
  ghcr.io/unishsys/berth:0.4.1 remotecluster
# open http://localhost:8081

Cluster reachable from the container? If your kubeconfig points at 127.0.0.1 (common with kind/minikube), add --network host (Linux) or use the host gateway so the container can reach the API server.

Verify the image (optional). Images are cosign-signed with GitHub OIDC, no keys to manage:

cosign verify ghcr.io/unishsys/berth:0.4.1 \
  --certificate-identity-regexp 'https://github.com/unishsys/.*' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

3 · Install with Helm

The production path: deploys Berth inside the cluster with RBAC and a generated auth token. The chart is an OCI artifact on GHCR.

Install the chart into a berth namespace. upgrade --install is idempotent, the same command installs the first time and upgrades after:

helm upgrade --install berth oci://ghcr.io/unishsys/charts/berth \
  --namespace berth --create-namespace \
  --version 0.4.1

Already have a key? Apply it in the same step by adding --set license.key='<YOUR_KEY>' (see Apply your key). --version pins a reproducible install; omit it to take the latest stable.

Read the auth token the chart generated (token auth is the secure default):

kubectl -n berth get secret berth-secrets \
  -o jsonpath='{.data.AUTH_TOKEN}' | base64 -d ; echo

Open it via a port-forward (or set up an Ingress, see below):

kubectl -n berth port-forward svc/berth 8081:8081
# open http://localhost:8081 and paste the token

Apply your license key

Berth is free to view. To make changes, add a license key: a freeCommunity key (up to 10 nodes) or an Enterprise key (node allowance agreed for your deployment). Get yours from your license account, it's verified offline, so it works in air-gapped clusters.

Helm

helm upgrade --install berth oci://ghcr.io/unishsys/charts/berth --reuse-values \
  --namespace berth \
  --set license.key='<YOUR_KEY>'

Binary or Docker

Set it as an environment variable:

LICENSE_KEY='<YOUR_KEY>' ./berth-linux-amd64 remotecluster
# Docker: add  -e LICENSE_KEY='<YOUR_KEY>'  to the docker run command

Logged-in users get copy-paste commands with the key already filled in on the in-app guide.

Verify it works

Open the dashboard, the license banner should show your tier and node cap, and Create/Edit actions are enabled once a key is applied. From the command line:

curl -s http://localhost:8081/api/v1/license \
  -H "Authorization: Bearer <AUTH_TOKEN>"
# token only needed when AUTH_MODE=token (the Helm default)

Expose it on a hostname (optional)

For a Helm install, turn on the Ingress and TLS instead of port-forwarding:

helm upgrade --install berth oci://ghcr.io/unishsys/charts/berth --reuse-values \
  --namespace berth \
  --set ingress.enabled=true \
  --set ingress.className=nginx \
  --set ingress.host=berth.your-domain.com \
  --set ingress.tls.enabled=true \
  --set ingress.tls.secretName=berth-tls

Berth has cluster-wide access, treat dashboard access as cluster access. Never run AUTH_MODE=none on a shared or exposed cluster, and always serve it over HTTPS.

Troubleshooting

The chart uses one replica, Recreate upgrades and persistent local RWO storage. Confirm your cluster has a suitable storage class. Review older Helm overrides before upgrading; shared RWX storage and multiple replicas are unsupported.

"Binary exits immediately." It needs a mode: run remotecluster (laptop) or incluster (pod).
CPU/memory graphs are blank. Your cluster has no metrics-server. Everything else still works.
Gateways / certificates show "not installed." Those CRDs (Gateway API, cert-manager) aren't present, expected, Berth degrades gracefully.
401 from the API. AUTH_MODE=token is on but no token was sent. Read it from the berth-secrets Secret (Helm step 2).
Docker can't reach the cluster. Your kubeconfig points at 127.0.0.1; add --network host or use the host gateway.

Need more than the Community node cap? See Enterprise. Prefer to grab a build first? Download Berth.