korvid v0.3.0

korvid v0.3.0

v0.3.0 makes destructive-operation previews materially more informative while
preserving korvid's approval and fail-closed audit boundaries.

Highlights

Graph-derived blast radius

Write confirmations can now include bounded dependency and dependent context
from korvid's resource graph. The preview keeps incomplete-evidence warnings
visible instead of presenting partial graph data as certainty.

Scale-down impact previews

Deployment, StatefulSet and ReplicaSet scale-down requests show bounded
controller and routing context before approval. The preview does not predict
which exact Pod Kubernetes will remove.

Pod resize impact previews

In-place pod resize requests summarize the affected containers and resource
changes alongside relevant graph context before approval.

Node maintenance impact previews

Cordon confirmations explain the node's local scheduling effect. Drain adds a
Pod eviction plan and, where available, bounded workload graph context and
disruption considerations.

MCP follow demonstration

The README now includes a short recording of GitHub Copilot CLI using korvid's
read-only MCP tools while the TUI follows from pods to logs and Helm releases.

Install or upgrade

Install the full feature set:

uv tool install 'korvid[all]==0.3.0'

Reinstall or expand extras explicitly:

pipx install --force 'korvid[all]==0.3.0'

Base TUI only:

uv tool install 'korvid==0.3.0'

Compatibility

• Python 3.11, 3.12 and 3.13 are supported.
• No intentional breaking configuration or provider/plugin API changes.
• Existing local configuration, audit records and retained state remain in
  their documented locations.

Safety posture

• Cluster reads and diagnostics remain read-only.
• Every cluster write still requires an operator approval keystroke.
• Every executed write still uses fail-closed audit logging: if the audit entry
  cannot be recorded, the mutation is blocked.
• External MCP clients receive read and UI-drive tools; optional write
  proposals still require review and approval in the TUI.

Verify

The GitHub Release publishes the wheel, source distribution, checksums, SBOM,
offline bundles and provenance attestations produced from the tagged commit:

set -eu
gh release download v0.3.0 --dir dist/v0.3.0
gh attestation verify dist/v0.3.0/korvid-0.3.0-py3-none-any.whl \
  --repo hellices/korvid
gh attestation verify dist/v0.3.0/SHA256SUMS --repo hellices/korvid
(cd dist/v0.3.0 && shasum --algorithm 256 --check SHA256SUMS)

Known limits

• Impact previews are bounded and can report incomplete evidence when RBAC or
  unavailable resource kinds prevent a complete graph.
• Performance qualification and remaining scale limits are documented in
  docs/performance.md.
• MCP log results are not credential-pattern masked by korvid; the connected
  external client owns its model and data boundary.

korvid v0.2.0

korvid v0.2.0

Operational context, without surrendering control. This release adds a
navigable Kubernetes relationship graph, a bounded session timeline,
read-only Prometheus/Loki investigation, MCP 2.0 support, Homebrew
distribution, and substantial large-cluster performance work.

Install or upgrade

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

For a new install:

uv tool install 'korvid[all]==0.2.0'
korvid

After the generated tap pull request is merged, Homebrew installs the TUI and
agent stack on macOS or Linux without relying on the system Python:

brew install hellices/korvid/korvid

The Homebrew formula deliberately excludes the MCP HTTP server. Install
korvid[mcp] or korvid[all] from PyPI when MCP is required.

install	adds
korvid==0.2.0	base TUI
korvid[agent]==0.2.0	embedded agent
korvid[mcp]==0.2.0	MCP server
korvid[agent,observability]==0.2.0	agent with Prometheus/Loki tools
korvid[mcp,observability]==0.2.0	MCP with Prometheus/Loki tools
korvid[all]==0.2.0	agent, MCP, and observability
korvid[all,entra]==0.2.0	all features plus Entra ID auth

Python 3.11–3.13 is supported on Linux, macOS, and Windows.

Relationship graph

Press g on a resource to open a bounded operational graph assembled from
Kubernetes facts rather than model inference. It connects:

• owners and owned resources;
• workloads, selectors, Pods, Services, and EndpointSlices;
• Ingress and Gateway API backends;
• volumes and PVCs;
• ConfigMap and Secret references without reading Secret values;
• PDB selectors and node placement.

Every edge records its evidence and whether it is declared, observed, or
inferred. Missing APIs, missing RBAC, unresolved references, cycles, and
traversal caps remain visible, so an incomplete graph never masquerades as
proof that no dependency exists.

Bounded session timeline

Press T to inspect what happened during this process:

• accepted watch ADDED, MODIFIED, and DELETED deltas;
• projected and redacted Kubernetes Warning Events;
• context-switch start, completion, and failure;
• write intent and outcome after the matching durable audit append succeeds.

The timeline is bounded by entry count and encoded bytes, partitioned by
context epoch, and filterable by epoch, source, and selected resource. Old
context rows may be inspected but cannot navigate into a same-named resource
in the current cluster. Cluster-authored text is bounded and rendered
literally.

Read-only observability

The optional observability extra adds bounded query_metrics and
search_logs tools for Prometheus and Loki to the agent or MCP surface; it has
no standalone base-TUI panel. They use a closed metric catalogue and escaped
Kubernetes scope rather than arbitrary model-authored PromQL or LogQL.
Credentials are resolved at call time, results are capped and masked, and the
tools are absent when no backend is configured.

See
docs/observability.md.

MCP 2.0

The MCP adapter now uses the 2.x SDK and explicitly threads request context
through handler dispatch. Tool failures remain in-band and the write approval
gate is verified through a real Streamable HTTP round trip. Existing
korvid --mcp usage remains the same; environments that pin korvid's transitive
MCP dependency should recreate or upgrade the tool environment.

Performance

The 1,000-Pod update path now:

• memoizes stable rendered rows;
• avoids re-seating an unchanged cursor;
• batches visible cell refreshes;
• keeps bucket order stable until the key set changes;
• caches AGE strings for their validity window.

The corrected performance report includes the full round-robin 2×2 comparison
and clearly separates table-update passes, row rebuilds, and display refreshes.
See
docs/performance.md.

Supply chain and release hardening

• Pre-commit and CI guards reject private mirror hosts in uv.lock and
  resolution-redirecting uv configuration.
• A dedicated Relock workflow can produce a PyPI-only lock when a local
  machine cannot reach PyPI directly.
• Release build requirements are exactly pinned and hash constrained.
• The Homebrew formula is generated from the verified PyPI-only lock.
• Wheel, sdist, checksums, SBOM, offline bundles, and Sigstore provenance are
  produced from one reviewed build.

Safety invariants

This release does not relax the write boundary:

• every write still requires a fresh user confirmation;
• RBAC, UID preconditions, context checks, and server dry-run remain in place;
• audit logging remains fail-closed;
• inferred graph edges and timeline entries are advisory and never approve or
  block a write by themselves;
• Secret values are never read to construct graph edges.

Verify

set -eu
gh release download v0.2.0 --dir dist/v0.2.0
gh attestation verify dist/v0.2.0/korvid-0.2.0-py3-none-any.whl \
  --repo hellices/korvid
gh attestation verify dist/v0.2.0/SHA256SUMS --repo hellices/korvid
(cd dist/v0.2.0 && shasum --algorithm 256 --check SHA256SUMS)

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

Known limits

• The graph is intentionally incomplete when APIs or permissions are missing;
  it is not a causal or outage-prediction engine.
• The timeline exists only for the current process and is not persistent
  multi-user history.
• Homebrew excludes MCP; use the PyPI extras for the HTTP server.
• Uninstalling korvid leaves configuration, audit records, cached logs, and
  keyring credentials in place. Cleanup is explicit in the
  release runbook.

---

Report vulnerabilities privately through
SECURITY.md, not a
public issue.

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.