korvid v0.1.2

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.