korvid

A tool-using bird for your cluster.

A keyboard-first Kubernetes TUI with an AI agent that works on the same screen as you. Browse and operate from the keyboard, let the embedded agent investigate alongside you, or connect your editor's assistant over MCP. All three drive the same cockpit; you approve every cluster write.

Documentation | Try it on a throwaway cluster | Latest release | PyPI

Watch the 28-second overview in HD (MP4)

Real TUI, synthetic cluster, edited excerpts. Agent: scripted model response with real read tools. MCP: local SDK client over Streamable HTTP, read-only calls. The ending explains approval policy; no cluster write is shown.

Why korvid

• Useful without AI. Browse resources, follow logs, inspect relationships, and operate workloads from a keyboard-first TUI. If you know k9s, the pod keys will feel familiar: : for commands, / to filter, d to describe, l for logs, and s for a shell.
• An agent that shares your screen. It sees the current view and selection, gathers evidence through structured tools, and opens the same panes you use. Normal keyboard input stays available.
• Bring your own assistant. Local MCP stdio connects an external host to the running TUI, rather than creating a second Kubernetes client.
• Approval is not delegated. Writes require a user keystroke and a fail-closed audit append. If the audit record cannot be written, the mutation is blocked. --readonly disables writes; protected contexts add confirmation.

How korvid compares

korvid overlaps with several good tools. In short:

| Tool | Focus | Where korvid differs | | --- | --- | --- | | k9s | A mature keyboard TUI with plugins, skins, and a read-only mode | The same style of cockpit, plus an agent and an MCP bridge that work inside it. If you never want AI, k9s is the more mature choice. | | kubectl-ai | A chat assistant that turns requests into kubectl operations, confirms modifying commands by default, and can run as an MCP server | korvid's agent has no shell or kubectl tool. It reads through bounded, structured tools, opens the panes you use, and its writes wait for an approval dialog that only your keystroke confirms. | | k8sgpt | Scanning a cluster with built-in analyzers and explaining findings with an LLM, from a CLI, an in-cluster operator, or an MCP server | korvid starts from a live view rather than a scan report: you and the agent work from what is on screen, then act from the same cockpit. | | HolmesGPT | Investigating alerts and incidents across Kubernetes and many other data sources, from a CLI, Slack, or an in-cluster operator that runs checks in the background | HolmesGPT reaches far more data sources and can run unattended. korvid is the hands-on cockpit for whoever is at the terminal, and beyond the Kubernetes API it queries only optional Prometheus and Loki backends. |

korvid's MCP server is the running TUI itself: every external read shows up on your screen, and opt-in write proposals wait for your approval there. The tools also combine well: a scanner or an alert agent can tell you something is wrong, and korvid is where you look and act. Descriptions follow each project's README as of October 2026; corrections are welcome.

Quick start

Requires Python 3.11+ and a working kubeconfig. uv can fetch a suitable Python automatically and installs korvid in an isolated tool environment:

uv tool install 'korvid[all]'
# or: pipx install 'korvid[all]'
korvid

These commands install the latest published package. For a reproducible pinned install and migration details, use the release notes. For unreleased main development, install the reviewed source instead:

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

python -m pip install 'korvid[all]' also works inside an activated virtual environment, including one created inside a container. Do not install into system Python or bypass PEP 668 with --break-system-packages: an externally-managed-environment error means you should use uv tool, pipx, or a venv.

No cluster you can experiment on? Practice on a throwaway kind cluster with one healthy and two deliberately broken workloads, then delete it with one command. Pointing korvid at a cluster that matters? Start with korvid --readonly: write keybindings are rejected and the agent is never offered a write tool.

Direct: use the keyboard

| Key | Action | | --- | --- | | : | Command bar: pods, deploy all, helm, ns <name>, ctx <name> | | / | Filter the table | | Enter / Esc | Drill down / back up | | d / l / s | Describe / logs / shell | | g | Resource dependencies and dependents | | Ctrl-A | Embedded agent panel | | ? | Every effective keybinding, including your remaps |

Shell/debug and port-forward operations require kubectl; Helm writes require helm. Browsing Helm releases does not require the Helm CLI.

Agent: choose a model, save a profile

Run :ai to search the model catalog and configure a connection. Named profiles keep independent models, endpoints, and authentication settings; once profiles exist, :ai opens the manager and Enter activates one. Use :model <reference> to change the active profile's model.

The bundled catalog covers over 2,000 models through LiteLLM. Use a local Ollama endpoint, a cloud API, an OpenAI-compatible server, or the supported GitHub Copilot sign-in flow. The low/high model tier adjusts tool and prompt budgets; automatic tier selection is the default. See agent setup and model search.

External assistant: connect over MCP stdio

Start the TUI first:

korvid --mcp

For VS Code, add this to .vscode/mcp.json:

{
  "servers": {
    "korvid": {
      "type": "stdio",
      "command": "korvid",
      "args": ["mcp", "stdio"]
    }
  }
}

The adapter privately discovers and authenticates to the running TUI. The host must run as the same user and find korvid on its PATH. No token belongs in host configuration or prompts.

Read and UI-drive tools are available; optional write proposals still wait for your approval in the TUI. Reconnect the host after switching cluster context or restarting MCP. Multiple instances require explicit selection. See MCP setup for other hosts and the tool-specific data boundary. OAuth, remote MCP, and headless mode are not part of this local flow.

Features

| Explore | What you get | | --- | --- | | Overview · Keybindings | The three interaction paths and keyboard guide | | Cluster browsing | Resource tables, split panes, metrics, multi-pod logs, filters, and session timeline | | Operations | Approval previews, node maintenance, tracked port-forwards, file transfer, and audit | | Relationships · Helm and operators | Bounded dependency graphs, release hierarchies, and install/upgrade workflows | | Agent · MCP | Screen-aware investigation and external assistant integration | | Provider extensions | SpecialFlow declarations for nonstandard transports and korvid.credential authentication chains | | Observability · Air-gapped operation | Bounded Prometheus/Loki queries, internal endpoints, and corporate CA trust | | Performance · Threat model | Measured limits, masking guarantees, and residual risks |

Cluster writes remain approval-gated and audited at every tier. Sensitive reads are masked at their documented boundaries; arbitrary log text is not guaranteed secret-free. External MCP hosts own their downstream model policy. Report vulnerabilities privately through SECURITY.md. For implementation details, see the architecture.

Watch MCP follow

One client. Korvid follows. A local MCP SDK client makes four read-only calls: list_resources, diagnose_pod, get_logs, and helm_list_releases. The TUI follows the unhealthy pod list, describe pane, logs, and Helm release. This recording uses the internal Streamable HTTP transport; configure new external hosts with stdio as shown above.

<details open> <summary>Show or hide the 14-second MCP follow animation</summary>

Recorded against the synthetic in-memory cluster, with no external client session metadata.

</details>

Status

The TUI, embedded agent, and local MCP integration are available in published releases. This README describes main; check the latest release for shipped changes, compatibility, and migration notes.

Installation

Install only the features you need:

uv tool install 'korvid'                       # base TUI
uv tool install 'korvid[agent]'                # embedded agent
uv tool install 'korvid[mcp]'                  # MCP server and stdio adapter
uv tool install 'korvid[agent,observability]'   # agent plus Prometheus/Loki
uv tool install 'korvid[mcp,observability]'     # MCP plus Prometheus/Loki
uv tool install 'korvid[all]'                  # full feature set
uv tool install 'korvid[all,entra]'            # also add Entra ID authentication

Choose one variant. To reinstall or expand an existing installation, specify the complete extra set instead of layering extras into a tool environment:

uv tool install --force 'korvid[all]'
# or
pipx install --force 'korvid[all]'

Tagged versions should be installed from PyPI; the source install in Quick start is for unreleased code. Without [agent], the agent panel and its keybindings are absent. Explicitly requesting a missing feature fails with an install hint, rather than silently enabling a partial configuration.

Homebrew users can run brew install hellices/korvid/korvid. The tap uses Homebrew's Python and follows its own reviewed update schedule. It excludes [mcp]; use PyPI fo