Documentation

Cluster Management

The cluster list is the entry point to all your environments. Kubeterm loads clusters automatically and gives you multiple ways to organize them.

• Zero Configuration: Automatically discovers and loads your default kubeconfig on desktop — no setup required after install.
• Tags & Filtering: Assign one or more tags to any cluster (e.g. production, staging, eu-west). The cluster list shows a tab per tag so you can instantly filter to a subset. Tag suggestions are offered when you type, based on tags already in use.
• Status Indicators: Each cluster entry shows a color-coded status (Ready / NotReady) so at-a-glance health is clear without opening the cluster.
• Source & Location Display: The list shows where each cluster came from — kubeconfig file, AWS, Azure, GCP, DigitalOcean — along with the cloud region if available.
• Reload kubeconfigs: A manual refresh button re-reads your local kubeconfig files to pick up any changes made outside of Kubeterm.
• Quick Access: Pin frequently used resources across any cluster to the Quick Access section in the left navigation for one-tap navigation.
• Multi-Tab View: Open multiple clusters or resource views simultaneously in tabs — middle-click or the context menu opens any item in a new tab.
• Tab Keyboard Shortcuts: Switch between open tabs with keyboard shortcuts for faster navigation.
• Cluster Actions: Right-click (desktop) or long-press (mobile) to edit tags, rename, or delete a cluster.

Cluster Settings

Each cluster has its own settings panel where you can configure:

• Display Name: Rename a cluster for display without changing the underlying kubeconfig name.
• Namespace Scope: Restrict the cluster view to one or more namespaces, or work across all namespaces at once.
• Per-Cluster Proxy: Override the global proxy with a different HTTP proxy for this cluster specifically.
• Local Authentication: Require biometric or device authentication before accessing this cluster or before performing write operations.
• API Server Endpoint, TLS & Auth: Review and update connection details, certificate authority data, and authentication method (username/password, client cert, or bearer token).

Multi-Cloud Support

Kubeterm connects directly to your cloud providers so you can load clusters without manually exporting kubeconfigs. Native authentication is used for each provider.

• AWS EKS: Load clusters using IAM credentials with STS and Signature V4 signing. Supports standard AWS credential chains.
• Google GKE: Cluster discovery and access via native Google Sign-In. Shows project name and ID during selection.
• Azure AKS: Integrated Microsoft authentication for AKS cluster loading.
• DigitalOcean: Connect and manage DigitalOcean managed Kubernetes clusters.
• OIDC: Universal support for OpenID Connect providers such as Okta, Auth0, and Keycloak — authenticate directly without storing tokens in kubeconfig.
• Kubeconfig Import: Paste or load a kubeconfig YAML directly to add any cluster that isn't from a supported cloud provider.

Cluster Dashboard

Opening a cluster shows a configurable dashboard of widgets. Each widget can be toggled on or off in cluster settings to fit your workflow.

• Nodes: Ready / NotReady / Other counts with per-node CPU and memory metrics. Links to the full node list.
• Namespaces: Active and inactive namespace counts with a link to the namespace list.
• Workloads: Running pod count, deployment ready ratio, and DaemonSet ready ratio — a quick sanity check for your workload health.
• Events: Warning / Normal / Other event counts so cluster-level problems surface immediately. Links to the full event list.
• Helm Applications: Deployed / Failed / Other release counts from Helm. Links to the Helm releases page.
• Argo CD Applications: Sync status (Synced, OutOfSync, Unknown) and health status (Healthy, Progressing, Degraded, Missing, Suspended, Unknown) for all Argo CD managed apps. Shows a clear message if Argo CD is not installed.
• Resource Shortcuts: A grid of common resource types (Pods, Services, Deployments, etc.) for one-tap navigation to any resource list.
• Recent Resources: A history of recently opened resources so you can jump back to something you were investigating without navigating from scratch. The history can be cleared at any time.

AI Assistance

Kubeterm includes built-in AI chat designed around real Kubernetes workflows. The AI can read your cluster state directly and surface results as interactive views inside the conversation.

Supported AI Providers

Bring your own API key for any of the supported providers. The AI settings let you configure multiple providers and switch between them:

• OpenAI (GPT models via /v1/chat/completions)
• Anthropic (Claude)
• Google Gemini
• DeepSeek

Each provider can be configured with a custom base URL, model name, temperature, and max token limit. Provider credentials are stored in secure storage. On Apple devices, AI provider settings can be synced via iCloud so you don't need to re-enter them on each device.

Chat Capabilities

• Cluster-Aware Context: Select which cluster to work in from the chat panel. When you open AI chat from inside a resource view (logs, resource list, etc.), the cluster and resource context are passed automatically so you don't need to re-specify what you're looking at.
• Embedded Results: AI responses can include live resource lists, describe output, YAML, and logs directly inside the conversation — no need to switch screens.
• Tool Use / kubectl Operations: The AI can perform read operations against the cluster API (listing resources, describing objects, fetching logs) to answer your questions with actual cluster data.
• Tool Policy: You control which kubectl operations the AI is allowed to perform. Restrict it to read-only or allow specific write actions.
• Streaming Responses: Responses stream in token by token. Models that support reasoning (thinking) show the reasoning steps before the final answer.
• Context Compression: Long conversations are automatically compressed to stay within model context limits while preserving the key details.
• Persistent History: Chat history is preserved across sessions for each cluster context.
• Failure Analysis: Analyze a failing resource directly from the resource detail view — the AI receives the resource manifest and recent events to help diagnose the issue.

Resource Visibility

Resource Lists

• All Standard Resources: Browse Pods, Deployments, StatefulSets, DaemonSets, ReplicaSets, Jobs, CronJobs, Services, Ingresses, ConfigMaps, Secrets, PersistentVolumes, Nodes, and more.
• Custom Resource Definitions: The CRD list is available and supports browsing instances of any CRD installed in your cluster.
• Namespace Filtering: Filter the resource list to one or more specific namespaces, or view all namespaces at once. The namespace selection is persisted per cluster.
• Column Customization: Control which columns appear in the resource table. Each resource type exposes relevant columns you can show or hide.
• Status Color Coding: Resources are highlighted with color-coded status chips that make failing or degraded states immediately visible.
• Responsive Views: On smaller screens or compact windows, resource lists switch to a card-based view with health signals. The full table view is used on wider screens.

Resource Detail

• Describe View: A structured breakdown of the resource — equivalent to kubectl describe — with sections for metadata, spec, status, conditions, volumes, and associated events. String lists are rendered as foldable token chips.
• YAML Editor: View and edit the full resource manifest with syntax highlighting. Changes can be applied directly to the cluster.
• Associated Events: The events for a resource are shown inline in the detail view so you don't need to navigate to the events list separately.
• Container Breakdown: For Pod resources, each container is listed with its image, ports, environment variables, volume mounts, and resource requests and limits.
• Node Metrics: Node detail includes real-time CPU and memory usage as well as the list of Pods currently running on that node.
• Compact Event View: On small screens, events have a dedicated compact card view that keeps the information readable without horizontal scrolling.

Apply YAML

• Manual Apply: Open the Apply panel to paste or type YAML and apply it to the cluster — equivalent to kubectl apply -f.
• File Import: Load a YAML file from your local filesystem rather than pasting.
• Apply History: Previously applied YAMLs are saved so you can re-apply them without retyping.
• Live Result Tracking: The result of the apply (created / configured / unchanged per resource) is shown in real time.

Troubleshooting Tools

Log Streaming

• All Workload Types: Stream logs from Pods, Deployments, DaemonSets, StatefulSets, ReplicaSets, and Jobs — not just individual pods. For higher-level workloads, logs from all underlying pods are aggregated.
• Multi-Pod Log Viewing: Select individual pods within a workload to view their logs separately or together.
• Multi-Container Selection: For pods with multiple containers, choose which container's logs to view.
• Follow Mode: Live-tail logs as they stream in, equivalent to kubectl logs -f.
• Search / Filter: Filter log lines by keyword to reduce noise when looking for specific events.
• Timestamps: Toggle timestamps on or off per session.
• Tail Size: Configure how many lines to load initially before following live output.
• Line Wrapping: Toggle line wrapping for wide log lines.
• ANSI Color Rendering: Log output with ANSI color codes is rendered with proper colors, making structured logs from frameworks like Logrus or Zap readable.
• Font Size: Adjust the font size of the log view independently.
• Export: Save the current log buffer to a file on your local device.

Port Forwarding

• One-Click Setup: Configure a port forward from a Pod or Service detail view — specify local and remote ports and start immediately.
• Persistent Sessions: Active port forwards are tracked in a dedicated list and survive navigation. You don't lose your forward by switching views.
• Multiple Simultaneous Forwards: Maintain several port-forward sessions at once, each visible in the port forward list with its configuration.
• Default kubeconfig Compatibility: Port forwarding works correctly alongside your default kubeconfig without conflicts.

Debug Containers

• Ephemeral Containers: Attach an ephemeral debug container to a running pod without restarting it, for situations where the existing container image lacks debugging tools.
• Node Debugging: Launch a debug container on a specific node to investigate node-level issues.

File Copy

• Copy from Pod: Transfer files from a running container to your local device — equivalent to kubectl cp.

Cluster Operations

• Scale Replicas: Adjust the replica count of a Deployment, StatefulSet, or ReplicaSet directly from the resource detail or list.
• Rolling Restart: Trigger a rolling restart on a Deployment, StatefulSet, or DaemonSet without downtime.
• Rollout Management: Pause, resume, and track rollouts.
• Delete Resources: Delete any resource with a confirmation dialog to avoid accidental removal.
• Node Cordon / Uncordon: Mark a node as unschedulable or schedulable again from the node detail view.
• Node Drain: Safely drain a node of its workloads before maintenance, with the same semantics as kubectl drain.
• CronJob Trigger: Manually trigger a CronJob run on demand without waiting for the scheduled time.
• Confirmation for Write Operations: All mutating operations show an explicit confirmation step so changes are never applied accidentally.
• Biometric Confirmation: Optionally require a fingerprint or Face ID confirmation before any write operation is applied to a cluster.

Helm Management

Release Management

• Release List: View all Helm releases across namespaces in one place, with chart version, app version, status (Deployed / Failed), and last deploy time.
• Release Details: Inspect the full release manifest and the values it was deployed with.
• Upgrade: Upgrade a release to a new chart version and edit values before applying.
• Rollback: Roll back a release to any previous revision from the release history.
• Uninstall: Remove a Helm release with confirmation.
• Values Viewer: View the computed values for any deployed release in a structured YAML editor.

Chart Discovery & Install

• Artifact Hub Browser: Search and browse Helm charts from Artifact Hub without leaving Kubeterm.
• Chart Details: View chart metadata, description, source links, and available versions.
• Configurable Install: Edit chart values in a structured editor before installing. Customize namespace, release name, and any chart-specific values.
• Install Progress: Track the installation in real time and see the resulting release status.

Argo CD

Kubeterm reads Argo CD application state directly from the cluster API. No separate Argo CD login or CLI is required — if Argo CD is installed in the cluster, its applications are visible immediately.

• Application List: View all Argo CD applications with their sync status and health status side by side.
• Sync Status: Synced, OutOfSync, and Unknown states are color-coded and surfaced on the cluster dashboard widget as well as the application list.
• Health Status: Healthy, Progressing, Degraded, Missing, Suspended, and Unknown health states are shown per application.
• Application Details: Open any application to see its full manifest, the git source repository, the destination cluster and namespace, and the resource tree of what the application manages.
• Sync: Trigger a sync operation from the application detail view.
• Refresh / Hard Refresh: Refresh application status from the source, or force a hard refresh to bypass any cache.
• Sync History: View the timeline of previous sync operations for an application.

Terminal

Exec and attach sessions open a full terminal emulator inside Kubeterm using an embedded XTerm engine.

• Exec into Container: Open a shell in any running container. A container selector is shown for pods with multiple containers.
• Attach: Attach to the main process's stdio of a running container.
• ANSI Color Support: Terminal output with ANSI escape codes is rendered with proper colors and formatting.
• Scrollback Buffer: A configurable scrollback buffer (default 5,000 lines) lets you scroll back through earlier output.
• Text Selection & Copy: Select and copy content from the terminal.
• Font Size: Zoom the terminal font in and out independently of the rest of the UI.
• Ctrl Sequences: Common control characters (Ctrl+C, Ctrl+D, etc.) are handled correctly.
• Mobile Keyboard: On mobile, a virtual keyboard overlay provides access to special keys (Tab, Escape, arrow keys, function keys) that don't appear on a standard soft keyboard.

Customization

• Theme: Light, dark, or system-based theme. The theme switch is available from the header on every page.
• Font Size: A global font size factor scales all text in the app for accessibility or dense-display preferences.
• Dashboard Widgets: Enable or disable individual widgets on the cluster dashboard per cluster.
• Resource Columns: Show or hide columns in resource list tables.
• Multi-Tab View: The tabbed navigation can be enabled or disabled. When enabled, opening a resource in a new tab keeps the current view intact.
• Connection Timeouts: Configure connect and receive timeouts for the Kubernetes API client globally.
• TLS Verification: Disable certificate verification globally for environments that use self-signed certificates.
• Default kubeconfig Path: Override the default kubeconfig file path used when loading local clusters.
• Global Proxy: Set an HTTP proxy for all cluster connections, or configure a different proxy per cluster.

Security & Privacy

• Local First: Cluster credentials and configuration never leave your device and are never sent to Kubeterm servers. All API calls go directly from your device to the Kubernetes API.
• Secure Credential Storage: AI provider API keys and cluster credentials are stored in platform secure storage (Keychain on Apple, credential store on Windows). On Linux and Windows, this can be toggled to use the system credential store or local encrypted storage.
• iCloud Sync: On Apple devices, cluster configurations and AI provider settings can be synced across your devices using iCloud Keychain.
• Biometric Lock: Require Touch ID or Face ID before accessing a specific cluster or before applying any write operation. Configured per cluster.
• Per-Cluster Proxy: Route cluster traffic through a different proxy than the global default — useful in environments with network segmentation.
• AI Tool Policy: Explicitly control which operations the AI assistant is permitted to run against the cluster API. Default is read-only.