k8m: a single-binary Kubernetes console with an MCP permission model

The gap k8m targets: a dashboard small enough to drop on a jump host

Most Kubernetes dashboards assume you will run them as a workload inside the cluster they manage, with an ingress, a database, and a persistent volume. k8m takes the opposite position. According to the README, all functionality is compiled into a single executable, and the primary install path is downloading a release binary and running ./k8m. The default listening port is 3618, and the default login is k8m / k8m. That shape suits a specific reader: the engineer who has kubeconfig files on a laptop or a bastion host and wants a UI without standing up a control plane for the UI itself.

The project is written in Go and licensed MIT. The README states it supports standard Kubernetes, AWS EKS, k3s, kind, and k0s cluster types, and that it runs on Linux, macOS, and Windows across x86 and ARM. The front end is built on Baidu AMIS, and the Kubernetes API client is a separate project by the same author, kom. That dependency split matters: k8m is not a thin wrapper around client-go in the way most dashboards are, and anyone evaluating the code should look at kom as well.

Where k8m departs from the usual dashboard brief is the AI layer. The README describes built-in support for Qwen2.5-Coder-7B and deepseek-ai/DeepSeek-R1-Distill-Qwen-7B, plus the ability to point at a private model, ollama included. The AI features listed are specific rather than general: selected-text explanation, resource guidance, YAML attribute translation, Describe output interpretation, log diagnosis, and run-command suggestions. The project also integrates k8sgpt, rendering its output in Chinese.

How the MCP layer is wired to cluster RBAC

The mechanism worth understanding is the MCP integration. k8m ships 49 built-in Kubernetes MCP tools, and the README says these can be composed into more than a hundred cluster operations. k8m can act as an MCP server for other model-facing software, and it can also consume MCP services from the wider ecosystem, with mcp.so named as a supported source. Every MCP invocation is logged in detail.

The permission model is the part that separates k8m from a generic tool-calling bridge. The README puts it as: whoever uses the model executes MCP with their own permissions. In practice that means a user who has read-only authorisation on a cluster cannot use the model to perform an exec or an administrative write, because the MCP call is evaluated against that user's cluster grants rather than a shared elevated identity. k8m's own permission system supports three cluster-level roles (read-only, Exec, cluster administrator), applies to users and user groups, and supports namespace allow and deny lists.

This is a real architectural decision, not a marketing line. Most MCP servers for Kubernetes are deployed once with a service account and hand every caller the same power. That is simpler to build and much harder to defend. k8m's approach costs more: it needs the dashboard's own identity system to be the source of truth for MCP authorisation, which means the user model, the group model, and the cluster grant model all have to stay consistent. The README does not describe what happens when they drift, and that is a gap worth probing in a test cluster before trusting it.

Running it: one binary, one compose file, and the flags that matter

The README gives two install paths. The first is the binary: download from the GitHub release page, run ./k8m, and open http://127.0.0.1:3618. The second, which the README calls recommended, is Docker Compose using the image registry.cn-hangzhou.aliyuncs.com/minik8m/k8m, publishing port 3618, mounting ./data into /app/data, and setting TZ to Asia/Shanghai.

The flag list is where the operational decisions live. --kubeconfig sets the kubeconfig path and defaults to /root/.kube/config. --in-cluster controls whether the host cluster is auto-registered and is enabled by default. --connect-cluster controls whether existing clusters are connected at startup and is off by default. --jwt-token-secret defaults to the string your-secret-key, which is a value you must replace before exposing the service. --login-type accepts password, oauth, or token, and defaults to password. --enable-temp-admin, paired with --admin-username and --admin-password, provides a temporary administrator account and is off by default. --print-config dumps the effective configuration, which is the fastest way to confirm what the binary actually loaded.

Two flags govern the shell features that reach into nodes and pods. --kubectl-shell-image defaults to bitnami/kubectl:latest and must contain the kubectl command. --node-shell-image defaults to alpine:latest and must contain nsenter. --image-pull-timeout defaults to 30 seconds. If your cluster pulls from a private registry or has no egress, those two image defaults will fail, and the README does not describe a fallback. On the storage side, the README states support for SQLite, MySQL, and PostgreSQL, so the persistence choice is yours rather than fixed.

Multi-cluster discovery and the assumptions baked into it

k8m's multi-cluster behaviour is described in the README as follows: it auto-detects in-cluster mode, and when a kubeconfig path is configured it scans the sibling files in that directory and registers each one as a managed cluster. Heartbeat checks and automatic reconnection are listed as features.

That is a convenient design for a laptop or a bastion with a ~/.kube directory full of contexts. It is also a design with a sharp edge. Directory scanning registers whatever it finds, so a stray kubeconfig left in that folder becomes a managed cluster. There is no described allowlist for which files get picked up; the control is the directory you point --kubeconfig at. If you want deliberate registration, keep the kubeconfig directory clean rather than relying on the scanner to be selective.

The same pattern shows up elsewhere. The README lists CRD auto-discovery with a tree view of all CRDs, a Helm market with repository management and one-click install, upgrade, and uninstall, and support for APIGateway and OpenKruise resources. Each of these widens the surface the dashboard can touch. None of them is described as opt-in at the resource level, though the README does say features are plugin-based and consume no resources when disabled. Which features are plugins and which are always on is not stated, and that distinction is worth confirming from the docs directory before you deploy.

Inspection, event forwarding, and where the AI actually sits

Two operational features are described in more detail than the rest. The first is scheduled cluster inspection: multiple clusters, custom rules, and Lua script rules, with results delivered to DingTalk, WeCom, Feishu, or a custom webhook, plus an AI summary. The second is Kubernetes Event forwarding: events from multiple clusters pushed to a webhook, filtered by cluster, keyword, namespace, or name, with multiple forwarding channels and an AI summary on top.

Both features end in the same place, an AI-generated summary. That is the honest centre of gravity for k8m's AI story. The model is not making scheduling or remediation decisions; it is compressing inspection output and event streams into prose, and separately answering questions about YAML, Describe output, and logs. The README's claim that the project is AI-driven should be read against that scope. The deterministic parts (rules, filters, webhooks) do the work; the model explains it.

One practical note on the AI path: the README states that k8m supports connecting your own private model, ollama included, and names two built-in model options. It does not document token costs, rate limits, or what happens when the model endpoint is unreachable during a scheduled inspection. If your inspection cadence depends on the summary arriving, that dependency is undocumented.

Where k8m is the wrong tool

k8m is not a replacement for kubectl, and it is not a policy engine. The README's permission model covers three cluster-level roles plus namespace allow and deny lists. It does not describe admission control, resource quotas, or any enforcement that survives outside the dashboard. If a user has kubectl access and a kubeconfig, k8m's permissions are irrelevant to what that user can do. The permission system governs the dashboard and the MCP path through it, nothing more.

The second limitation is the default posture. Username k8m, password k8m, JWT secret your-secret-key, and in-cluster registration on by default. The README explicitly tells you to change the credentials and enable two-factor authentication after going live. That is a reasonable instruction and an unreasonable default for anything reachable from a network you do not control. Two-factor authentication is listed as a topic on the repository, and the README mentions enabling it, but the setup flow is not in the supplied material.

The third is documentation depth. The README points to a docs directory, a changelog, and two external design-document sites. From the README alone you cannot determine how MCP tool permissions are evaluated step by step, what the inspection rule schema looks like, or how the Lua rules are sandboxed. If your evaluation depends on any of those, the README will not settle it.

For comparison, consider the Kubernetes Dashboard project or k9s. The Kubernetes Dashboard is the upstream, in-cluster web UI: it authenticates against the cluster's own identity, runs as a cluster workload, and does not embed a model or an MCP server. k9s is a terminal UI that reads your kubeconfig directly and has no server component at all. k8m sits between them: a server-based UI like the Dashboard, but deployable as a single binary like a CLI tool, with an AI and MCP layer neither of the others has. If your requirement is cluster-native authentication and nothing else, the upstream Dashboard is the smaller commitment. If your requirement is a terminal, k9s is the smaller commitment. k8m's case rests on the AI and MCP features being worth the extra component.

Maintenance cadence and what MIT actually gives you

The release history in the repository metadata shows v0.26.17 in March 2026, v0.26.18 in August 2026, and v0.26.19 in September 2026. The version numbering stays in the 0.26.x line across those releases, which suggests incremental changes rather than a stabilisation milestone. Anyone planning a long-lived deployment should read the CHANGELOG rather than infer stability from the version prefix, because the README does not state a support policy, a deprecation window, or a compatibility guarantee for configuration flags.

The upgrade cost is shaped by the deployment model. A single binary or a Compose service means upgrading is replacing an image tag or a file, with state in ./data or in an external database. The README lists SQLite, MySQL, and PostgreSQL, so a deployment on SQLite has the simplest upgrade path and the least operational overhead. The configuration surface is flags plus whatever the docs directory describes, and the README's --print-config flag is the direct way to diff effective configuration between versions.

Licensing is MIT, which the README describes as permitting commercial use and free modification. That is a permissive licence and it is stated plainly. It does not grant anything regarding the models you connect to k8m, and the README's mention of Qwen2.5-Coder-7B and DeepSeek-R1-Distill-Qwen-7B does not say how those weights are licensed or whether they are bundled. That is a question for your own legal review, not something the README answers. The MIT grant covers k8m's source, and the README says the source is fully open with no restrictions.

Editorial conclusion

k8m fits teams that want a small Kubernetes console with AI assistance and are willing to run it next to a private model endpoint. It is a poor fit for anyone who needs a hardened, audited access layer: the default credentials are k8m/k8m, the JWT secret defaults to your-secret-key, and the README itself says to change both after going live. Before adopting, verify the MCP permission mapping on a non-production cluster, confirm your model endpoint is reachable, and check which of the 49 MCP tools your cluster's RBAC would actually allow.

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. weibaohui/k8m on GitHub