Authentication

Kubyl understands the auth methods kubeconfigs use. Secrets such as tokens and refresh tokens go to the OS keychain and never into settings.json, state.json, your kubeconfig or the logs.

Supported methods#

Exec plugins#

• On macOS and Linux Kubyl uses the PATH of your login shell, so tools installed with Homebrew, asdf or a cloud SDK are found even when you start Kubyl from the Dock.
• The plugin timeout is 300 seconds. On failure, the plugin's stderr is shown.
• Short-lived credentials from cloud plugins are cached in memory for part of their life, then fetched again. They are never written to disk.
• Plugins that return a client certificate and key (clientCertificateData) work. Kubyl hands them to the TLS layer in the right encoding.
• Interactive plugins (interactiveMode: Always) get a prompt dialog with their output and a line for input. This is not a real terminal, so a plugin that checks for a TTY behaves as if it were non-interactive.
• Kubeconfigs you paste, import or create run commands on your machine. Kubyl asks for explicit consent first: I checked these commands and trust them.

OIDC sign-in#

When a context needs an OIDC login, the sign-in dialog offers:

• Browser: authorization code with PKCE and a loopback redirect. Use Reopen browser if the tab was closed.
• Use device code: shows a code to enter on another device.

Refresh tokens are kept in the OS keychain, so you sign in again only when they expire. A refresh token is dropped only when the provider answers invalid_grant, so a network error or a slow provider doesn't sign you out. Signing out cancels a sign-in that is still in progress.

OpenShift#

For OpenShift tokens (sha256~…) Kubyl offers the same three routes as the oc CLI:

• Web login, like oc login --web.
• Username and password, like oc login -u.
• Pasting a token from the console's Copy login command page.

Tokens are stored per API server and user. The token in your kubeconfig is never written back. A token that the API server treats as anonymous is rejected at sign-in instead of being kept.

Credential storage#

Kubyl uses macOS Keychain, Windows Credential Manager or the Secret Service on Linux. Signed macOS release builds use the data-protection keychain, so there are no repeated prompts. Builds you compile yourself fall back to the login keychain, which asks again whenever the binary changes. Windows Credential Manager limits the size of an entry, and very large tokens may not fit.

Everything Kubyl stores goes through one credentials store: OIDC and OpenShift tokens, Argo CD sessions and passwords for Prometheus or Alertmanager behind basic auth. Exec credentials are kept in memory only. For development, KUBYL_CREDENTIAL_STORE=file writes plaintext JSON and memory forgets everything on quit. See Files and environment.

When a context has no stored sign-in, the desktop app falls back to a token written into the kubeconfig, for example by oc login. The Kubyl Server does not do that: it ignores tokens in kubeconfigs, so a missing sign-in stays missing instead of acting as the kubeconfig's author.

Where your sign-in goes#

Features that call other programs on your behalf never put a token into command-line arguments or files.

• Helm runs with --kubeconfig and --kube-context. For contexts that sign in through Kubyl (OIDC, OpenShift) the current token goes into HELM_KUBETOKEN in helm's environment only. Exec plugins, client certificates and static tokens stay with the kubeconfig. Your own HELM_KUBE* variables are removed so Kubyl's flags decide the cluster. See Helm.
• AI agents never receive your token. Their KUBECONFIG points to an empty file unless you set agent.kubectl to context, and then only for contexts without inline credentials. See AI agents.
• Local terminal tabs get a kubeconfig that holds only that context. A context that signs in through Kubyl gets its token in the environment variable KUBYL_KUBE_TOKEN, read by an exec plugin in that kubeconfig. It is the sign-in at the time the tab opened, so open a new tab after it expires. Available in the release after 0.6.0. See Terminal.