KubeRich

A keyboard-driven Kubernetes workspace for your terminal, built with Python and Textual.

Get started · Installation · User guides · Contribute

Browse a cluster, inspect a workload, follow its logs and open a container shell without losing your place. KubeRich is an independent Apache-2.0 project, inspired by K9s and built by Python enthusiasts. All capabilities are open source, with no paid feature tiers.

Actual application render using fictional resources and an owned local API. No customer contexts, credentials or production resources are used in this demo.

First release

The first release line is 0.1.0. Its source candidate is usable; public PyPI, Homebrew and GitHub download activation remains under the release procedure. Use a trusted checkout or supplied wheel while those channels are unavailable.

Linux and macOS are the initial targets, with CPython 3.12–3.14 for source installation. Four standalone archives have separate native qualification. The installation guide states the actual host/architecture scope and limits. Stable 1.0 compatibility and complete K9s parity are later milestones.

What you can do

Use --readonly for your first connection; the default preference permits writes. Effectful actions require captured targets and the corresponding Kubernetes permissions; reviewed changes also require confirmation. Metrics, user plugins and advanced node/debug operations remain planned; see the maintained resource views and release phases.

Run from source

With uv and Python 3.12, 3.13 or 3.14, run from a trusted checkout:

uv sync --locked --group dev
uv run kuberich --version
uv run kuberich config check
uv run kuberich --context demo-lab --namespace demo-apps --readonly

demo-lab and demo-apps are fictional example names. Replace them with an explicitly intended context and namespace. Add --kubeconfig /absolute/path/to/config when needed; --config instead selects KubeRich preferences. Configured authentication helpers are trusted local programs. Version, help, info and config check do not connect to a cluster or execute helpers. The interface needs an interactive terminal; python -m kuberich is also supported.

For an isolated supplied wheel or future PyPI/Homebrew/archive installation, follow installation and upgrades. The project-owned Homebrew target is brew install kuberich/tap/kuberich after public activation.

A few keys to begin

In a live shell, keys go to the remote program. exit/Ctrl+D returns to containers; Ctrl+] closes the owned session. See the guided workflow and shell controls.

Documentation

The maintained Markdown guides generate both website surfaces. CLI/resource references come from application declarations; authored explanations are reviewed with the behavior they describe. The current approved development hosts are website and docs; they retain their recorded deployment until the final candidate is approved for publication.

• Install, upgrade and uninstall
• First launch and guided everyday workflow
• Contexts and authentication, EKS and AKS
• Navigation and completion, logs and shells
• Guarded changes, manifest editing and workload operations
• Troubleshooting and terminal compatibility

Development and quality

Read CONTRIBUTING.md, the architecture and the selected GitHub issue before changing behavior. Work proceeds through short-lived issue branches, signed-off commits, checked PRs and squash merges.

The quality policy enforces at least 90% line and branch coverage separately, 90% changed-line coverage and 100% for designated critical deterministic modules. Behavioral, actual PTY, owned Kubernetes and clean-install checks complement coverage. Real-provider and physical-terminal certification limits remain explicit; a percentage does not prove every environment.

See current checkpoints, roadmap, backlog, distribution and release/versioning procedure for measured progress and delivery.

Community and license

Issues welcome bugs and proposals. Please follow the code of conduct; use the security policy for vulnerability reports.

Apache-2.0. Copyright (c) 2026 Carlos Herrera and KubeRich contributors. NOTICE and the licensing guide explain attribution and derivative permissions.