Getting Started

First launch

Kubius reads your kubeconfig from ~/.kube/config on launch. Every context defined there shows up in the Clusters section at the top of the left sidebar. Contexts are sorted alphabetically; the active one is marked with a green dot.

If you have no kubeconfig, or it’s in a non-standard location, the welcome screen will tell you. Set the KUBECONFIG environment variable in your shell profile before launching Kubius if you keep your configs elsewhere.

Connecting to a cluster

Click any context in the sidebar to connect. Kubius starts watch streams for every supported resource type in parallel. The sidebar reveals after one second whether or not the streams are ready - resource counts populate as their lists arrive, so you’ll see numbers climb as more data flows in.

If the cluster is unreachable (network failure, expired certificate, wrong endpoint) the dot turns red and the sidebar shows a “Connection failed” message with the error and a Retry button.

Authentication

Kubius supports every standard kubeconfig auth method:

• Bearer tokens - static or from an exec plugin
• Client certificates - client-certificate-data / client-key-data
• Exec plugins - gke-gcloud-auth-plugin, aws eks get-token, kubelogin, etc.
• Custom CA certificates - base64-encoded PEM in certificate-authority-data

Exec plugins are invoked through your login shell ($SHELL -l -c ...) so PATH includes gcloud, aws, and friends - even when launching from Finder.

Tokens returned by exec plugins are cached until expiry. You won’t see the gcloud prompt or AWS round-trip on every API call.

The main layout

Kubius uses a three-column layout:

• Sidebar (left) - clusters, namespace selector, pinned resources, resource type list
• Resource list (centre) - the rows for whichever type you selected (Pods, Deployments, etc.)
• Detail panel (right) - opens when you click a row

Double-click a row to open it in its own window instead of the right panel. Re-opening the same resource brings the existing window to the front.

Switching namespaces

The namespace selector (in the toolbar, and mirrored at the top of the sidebar) controls which namespaces every list is scoped to. It’s a multi-select: click it to open a searchable sheet with an All Namespaces master checkbox and a checkbox per namespace. All Namespaces is the default - Kubius shows everything cluster-wide. Tick one or more namespaces to narrow things down, or hit Clear to deselect everything (which then shows only non-namespaced items). The button summarises your choice - “All Namespaces”, a single namespace name, or “N namespaces”.

System namespaces (kube-system, kube-public, gke-system, etc.) are pushed to the bottom of every list. Toggle the System button in the filter bar to hide them entirely.

Switching clusters

Click another cluster in the sidebar. Kubius tears down all watches for the previous cluster, closes any transient windows that were spawned against it (detail mini-windows, log windows, port-forward terminals), and starts fresh.

You can also use Context → Switch Context in the menu bar.