Skip to content

korvid v0.1.2

The first public release. An AI-native Kubernetes TUI: a keyboard-first cockpit with an embedded agent that reads your cluster, explains what it found, drives the interface for you — and can never execute a change you did not approve.

Install

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

korvid is an application, so install it in its own environment rather than into whatever Python is active. Prefer uv if you have neither tool: korvid needs Python 3.11+, which is newer than the system Python on macOS and on most enterprise Linux, and uv fetches a suitable interpreter for you.

Python 3.11–3.13 on Linux, macOS and Windows. korvid alone installs the base TUI; the extras are separable if you want a smaller surface:

install adds
korvid==0.1.2 the TUI only — no agent, no MCP server
korvid[agent]==0.1.2 the embedded agent (:ai, Ctrl-A)
korvid[mcp]==0.1.2 the MCP server (korvid --mcp)
korvid[all]==0.1.2 both — the recommended first install
korvid[all,entra]==0.1.2 adds Entra ID auth for Azure OpenAI

Air-gapped? Every release ships verified offline bundles for Linux and Windows x86-64 on 3.11–3.13. See docs/airgap.md.

What you get

A cockpit, not a resource browser. Navigate any kind with : commands, filter with / — fuzzy, regex, or label selectors — and drill down with Enter: pods to containers, deployments through replica sets to pods, a Helm release or operator into the tree of everything it installed. Split the workspace into two panes and sort on live data. Pods carry live CPU and memory against their enforced limits, and a troubled pod explains itself in a hint strip built from real API data before you open describe.

An agent that operates the TUI. Ctrl-A opens a chat panel that already knows what you are looking at — view, namespace, selection, filter. It inspects the cluster through read-only tools and then drives the interface: "show me the crashing pod's logs" navigates, filters, and opens the log pane. Secret data is masked before it reaches the model. Works with GitHub Copilot, Azure OpenAI, Anthropic, OpenAI, local Ollama, or any OpenAI-compatible endpoint — including a small profile tuned for 3B–14B local models.

Operations that beat their kubectl equivalents. Port-forwards are session-tracked, so :pf lists them with live status, a forward whose pod dies flips to broken with a toast instead of failing silently, and every one is torn down on exit. File transfer rides the exec API as a tar stream — no kubectl cp, no kubectl binary — with path browsing on both ends and downloads that never leave a half-written file.

An MCP server. korvid --mcp exposes the same read and UI-drive tools to an external agent, with DNS-rebinding protection and Origin validation on by default.

The safety model

This is the part to read before pointing it at production.

  • Every mutation is approval-gated. Yours and the agent's alike: nothing executes until you confirm it in a dialog. The agent can request a delete, scale, restart or resize. It cannot execute one.
  • Every executed write is audited, fail-closed. If the audit entry cannot be written, the write is blocked rather than performed unrecorded.
  • Reads are read-only by construction, and secret values are masked before they leave the process.
  • Kubernetes API writes additionally get a best-effort RBAC pre-check and a server-side dry-run preview in the confirmation dialog where the API supports one.
  • --readonly disables writes entirely. protected_contexts demands typed-name confirmation on the clusters you name.

Full threat model: docs/threat-model.md.

Verify

Artifacts are built once and promoted unchanged to PyPI and this release, with Sigstore build provenance recorded in the public Rekor log:

gh release download v0.1.2 --dir dist/v0.1.2
gh attestation verify dist/v0.1.2/korvid-0.1.2-py3-none-any.whl --repo hellices/korvid
gh attestation verify dist/v0.1.2/SHA256SUMS --repo hellices/korvid
(cd dist/v0.1.2 && shasum --algorithm 256 --check SHA256SUMS)

An SBOM for the full dependency set ships with the release.

Known limits

  • No upgrade path is proven yet. The install matrix covers clean installs and uninstalls of every extra combination on three operating systems and three Python versions, but there is no earlier PyPI release to upgrade from. The next release validates that.
  • v0.1.0 and v0.1.1 are tagged but were never published — the first failed before build, the second stopped at PyPI publication. They remain as immutable audit history, so 0.1.2 is the first version you can install.
  • Extras do not expand in place. If you installed korvid and now want the agent, reinstall the full requirement (korvid[all]==0.1.2) rather than adding the extra on its own.

Uninstalling

pip uninstall korvid leaves your config, audit log, cached logs and any stored OS-keyring credential in place — deliberately, since the audit log is a record. Cleanup is explicit and documented in the release runbook.

Reporting a vulnerability: SECURITY.md. Please do not open a public issue for security reports.