Getting started¶

Five minutes from an empty terminal to a running cockpit.

Requirements¶

Python 3.11 or newer on Linux, macOS, or Windows. CI currently qualifies 3.11, 3.12, and 3.13.
A working kubeconfig — korvid reads the same config, contexts, and credential plugins as kubectl.
The Helm and operator views do not require the Helm CLI; they read release data from the cluster. Helm write actions require helm on PATH, while shell/debug fallbacks require kubectl. korvid looks for kubectl once per session, at startup: install it while korvid is running and restart to pick it up.

korvid is an application, not a library: install it into its own isolated environment rather than whatever Python happens to be active. uv and pipx both do this for you; a bare pip install --user does not.

Current release¶

Homebrew installs the version currently published by the live tap. The uv tool and pipx commands below install the latest published package from PyPI. Check the latest release for its version, pinned installation commands, and migration notes. Most users should stop at Install; use Development build only when you need an unreleased change from main.

Install¶

Homebrew (macOS and Linux)¶

The live Homebrew tap needs no system Python:

brew install hellices/korvid/korvid

The tap follows its own reviewed update schedule; brew info hellices/korvid/korvid shows the available version. The formula builds against Homebrew's Python and deliberately excludes MCP. Use uv tool or pipx below for the MCP server and stdio adapter.

`uv tool` (recommended cross-platform)¶

uv tool install 'korvid[all]'
korvid

uv fetches a suitable Python interpreter automatically, which matters on macOS and most enterprise Linux where the system Python predates 3.11.

`pipx`¶

pipx install 'korvid[all]'
korvid

Choose your extras¶

korvid alone installs only the TUI. Add extras for the agent, MCP server, or both:

Install	Adds
`korvid`	The keyboard-first TUI only — no agent, no MCP server
`korvid[agent]`	The embedded agent (`Ctrl-A`, `:ai`, `:model`)
`korvid[mcp]`	The MCP server (`korvid --mcp`) and local adapter (`korvid mcp stdio`)
`korvid[agent,observability]`	Embedded agent plus Prometheus/Loki investigation tools
`korvid[mcp,observability]`	MCP server plus Prometheus/Loki investigation tools
`korvid[all]`	Agent, MCP, and observability connectors — the recommended first install
`korvid[all,entra]`	Everything above, plus Entra ID auth for Azure OpenAI

Extras do not expand in place: if you installed korvid alone and later want the agent, reinstall with the full extra set you want rather than layering extras on top of an existing install.

First run¶

korvid

korvid opens on the pods table for your current kubeconfig context and namespace. No agent, no MCP server, and no network calls beyond the Kubernetes API happen unless you ask for them.

Press : and type a resource name (pods, deploy all, helm, …) to navigate.
Press ? any time for the full in-app help overlay.
Press q or Ctrl-C to quit.

Development build¶

The guides describe main, which can include changes not yet published. To test the reviewed source instead of the latest PyPI release:

uv tool install 'korvid[all] @ git+https://github.com/hellices/korvid'

Ten keys to get moving¶

Key	Does
`:`	Open the command bar (`pods`, `ns <name>`, `ctx <name>`, `ai`, `q`, …)
`?`	Open the help overlay — every keybinding, in context
`/`	Filter the current table (fuzzy, `/regex/`, or `-l label=value`)
`Enter`	Drill into the selected resource (pods → containers, deploy → pods, …)
`Esc`	Pop back up one drill-down level
`d`	Describe the selected resource (manifest + events)
`l`	Open the log pane for the selected pod
`g`	Show the operational relationship graph for the selected resource
`Ctrl-A`	Open the embedded agent panel (requires the `[agent]` extra)
`Ctrl-D`	Delete the selected resource, with a confirm dialog

The full, always-current key reference — grouped by context, including node, Helm, and operator actions — lives in keybindings.md.

Where to next¶

Learn the cockpit: Browsing the cluster covers tables, filters, custom columns, the split workspace, and the log viewer in depth.
Add the agent: The embedded agent explains what it can see, which tools it can call, and how to point it at a provider.
Connect an external client: The MCP server exposes the same read and UI-drive tools to VS Code, Claude Code, Cursor, or Zed.
Running without internet access? Air-gapped operation covers offline bundles and internal trust configuration.