{
  "markdown": "<div align=\"center\">\n  <img src=\"assets/avatar.png\" alt=\"kubeleash logo\" width=\"132\" height=\"132\" />\n  <h1>kubeleash</h1>\n  <p><strong>Point it at your over-privileged kubeconfig — it still can't nuke prod.</strong></p>\n</div>\n\n[![CI](https://github.com/kubeleash/kubeleash/actions/workflows/ci.yml/badge.svg)](https://github.com/kubeleash/kubeleash/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/kubeleash/kubeleash)](https://goreportcard.com/report/github.com/kubeleash/kubeleash)\n[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/kubeleash/kubeleash/badge)](https://scorecard.dev/viewer/?uri=github.com/kubeleash/kubeleash)\n[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)\n[![Release](https://img.shields.io/github/v/release/kubeleash/kubeleash?sort=semver)](https://github.com/kubeleash/kubeleash/releases/latest)\n\n**Guardrails for AI agents on your cluster.** kubeleash is a local\n[MCP](https://modelcontextprotocol.io) server for Kubernetes whose\ndifferentiator is RBAC-style, *context-scoped* access control. Point it at a\nkubeconfig — even a cluster-admin one — and a local policy file constrains what\nthe agent can actually do, **per kube context**, with destructive actions gated\n**before any call reaches the cluster**.\n\n<div align=\"center\">\n\n### Add kubeleash to your AI client\n\n[![Add to VS Code](https://img.shields.io/badge/Add%20to-VS%20Code-007ACC?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=kubeleash&config=%7B%22name%22%3A%22kubeleash%22%2C%22command%22%3A%22kubeleash%22%2C%22args%22%3A%5B%22--policy%22%2C%22%24%7Binput%3ApolicyPath%7D%22%5D%2C%22inputs%22%3A%5B%7B%22id%22%3A%22policyPath%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Path%20to%20your%20kubeleash%20policy.yaml%22%7D%5D%7D) &nbsp; [![Add to Cursor](https://img.shields.io/badge/Add%20to-Cursor-0098FF?style=for-the-badge&logo=cursor&logoColor=white)](#install) &nbsp; [![Claude Code / Desktop](https://img.shields.io/badge/Add%20to-Claude-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](#install)\n\n<sub>Install launches the local <code>kubeleash</code> binary &mdash; get it via <code>brew</code>, <code>go install</code>, or the container (see <a href=\"#install\">Install</a>). VS Code installs in one click; Cursor &amp; Claude open the <a href=\"#install\">setup steps</a> (GitHub strips the <code>cursor://</code> one-click link, so it lives there as copy-paste).</sub>\n\n</div>\n\n## Why\n\nMost Kubernetes MCP servers inherit the kubeconfig's permissions wholesale —\nwhatever the credentials grant, the agent can do. kubeleash adds three things\nnative RBAC can't express for this use case:\n\n- **Constrain the agent independently of the credentials.** Effective access is\n  always `kubeconfig-grants ∩ policy-allows` — kubeleash only ever *subtracts*.\n- **Context-aware guardrails.** Policy varies by context (prod vs staging vs\n  dev); native RBAC is per-cluster.\n- **Block destructive verbs** (`delete`/`exec`/…) as a safety net against agent\n  mistakes and prompt injection.\n\n## What kubeleash enforces\n\nkubeleash governs only the calls routed **through** it. It provides a hard\nguarantee when it is the agent's *sole* path to the cluster. An agent that also\nhas shell access (raw `kubectl`, `oc`, the API) can step around it, so in a\nshell-enabled assistant kubeleash is advisory — pair it with the\n`using-kubeleash` skill, which instructs the agent to stop (not reach for\nkubectl) when the leash is unavailable.\n\n## Policy in 10 seconds\n\n```yaml\npolicies:\n  - contexts: \".*prod.*\"          # regex over the active context name\n    allow:\n      resources: [\"*\"]\n      verbs: [get, list, watch]   # read-only in prod\n    deny:\n      verbs: [exec]               # never, regardless of credentials\n```\n\nDeny wins. Default deny. A broken policy refuses to start — it never fails open.\n\nSee [`examples/policy.yaml`](examples/policy.yaml) for a fuller, commented policy\n(read-only prod, broader staging, namespace-scoped dev).\n\n## Quickstart\n\nInstall it (Homebrew shown — see [Install](#install) for `go install` and the\ncontainer), then exercise a policy without touching any cluster:\n\n```bash\nbrew install kubeleash/tap/kubeleash\n\n# Grab the commented example policy:\ncurl -fsSL https://raw.githubusercontent.com/kubeleash/kubeleash/main/examples/policy.yaml -o policy.yaml\n\n# See how kubeleash validates and normalizes a policy (no cluster needed):\nkubeleash --policy policy.yaml --print-effective-policy\n\n# Try it without touching any cluster — every decision is logged, nothing runs:\nkubeleash --policy policy.yaml --dry-run\n```\n\nPrefer source? `git clone https://github.com/kubeleash/kubeleash && cd kubeleash\n&& go build -o kubeleash ./cmd/kubeleash` (Go 1.26+).\n\nThen point an MCP client at it (see [below](#use-it-as-an-mcp-server)). kubeleash\nspeaks MCP over stdio, so it's launched by your client, not run as a daemon.\n\n| Flag | Purpose |\n|------|---------|\n| `--policy <path>` | Policy file. **Required** (or set `K8S_MCP_POLICY`); with neither, kubeleash refuses to start — default-deny never fails open. |\n| `--kubeconfig <path>` | Explicit kubeconfig. Omit to use the standard client-go rules (`$KUBECONFIG`, `~/.kube/config`). |\n| `--dry-run` | Evaluate + log every decision, but never execute against a cluster. |\n| `--print-effective-policy` | Print the resolved/normalized rules and exit. |\n| `--log-level <level>` | `debug` / `info` / `warn` / `error` (default `info`). The audit log is JSON on **stderr** (stdout is the MCP transport). |\n| `--version` | Print version, commit, and build date. |\n\n## Install\n\nAll channels run kubeleash **locally over stdio** — your client launches the\nbinary; nothing is hosted. kubeleash is listed in the\n[official MCP Registry](https://registry.modelcontextprotocol.io) as\n`io.github.kubeleash/kubeleash`, so registry-aware clients can discover it too.\n\n### One-click\n\nThe **Add to Cursor / VS Code** buttons\n[at the top](#add-kubeleash-to-your-ai-client) are the fastest path (they need\nthe `kubeleash` binary on PATH — see [Manual](#manual)). Other clients:\n\n**Claude Code** — this repo is its own plugin marketplace:\n\n```shell\n/plugin marketplace add kubeleash/kubeleash\n/plugin install kubeleash@kubeleash\n```\n\nNo separate install step: on first run the plugin uses a `kubeleash` already on\nyour PATH, or otherwise downloads the matching release binary (verifying its\nchecksum) and caches it.\n\nSafe by default — no policy authoring required first: if you have no policy at\n`~/.kubeleash/policy.yaml`, the plugin writes a **read-only starter** there on\nfirst run (allow `get`/`list`/`watch`, deny `exec`/`delete`). Review and widen\nit to grant more access. (This convenience is the plugin's only; the raw binary\nstill **requires** an explicit `--policy` and refuses to start without one.)\n\nThe plugin also ships two skills — `using-kubeleash` (how an agent should query\nand act through the gated tools) and `authoring-kubeleash-policy` (how to write\nthe policy) — so the agent understands the guardrails, not just the tool list.\n\n**Claude Desktop** — download `kubeleash.mcpb` from the\n[releases page](https://github.com/kubeleash/kubeleash/releases) and\ndouble-click it; the bundle ships the binary and prompts you for the policy and\nkubeconfig.\n\n<details>\n<summary>Raw Cursor / VS Code deeplink URLs (if a button doesn't fire)</summary>\n\nCursor (can't prompt — edit the placeholder path afterward in *Settings → MCP*).\nDecodes to `{\"command\":\"kubeleash\",\"args\":[\"--policy\",\"/absolute/path/to/policy.yaml\"]}`:\n\n```\ncursor://anysphere.cursor-deeplink/mcp/install?name=kubeleash&config=eyJjb21tYW5kIjoia3ViZWxlYXNoIiwiYXJncyI6WyItLXBvbGljeSIsIi9hYnNvbHV0ZS9wYXRoL3RvL3BvbGljeS55YW1sIl19\n```\n\nVS Code (prompts for the policy path):\n\n```\nvscode:mcp/install?%7B%22name%22%3A%22kubeleash%22%2C%22command%22%3A%22kubeleash%22%2C%22args%22%3A%5B%22--policy%22%2C%22%24%7Binput%3ApolicyPath%7D%22%5D%2C%22inputs%22%3A%5B%7B%22id%22%3A%22policyPath%22%2C%22type%22%3A%22promptString%22%2C%22description%22%3A%22Path%20to%20your%20kubeleash%20policy.yaml%22%7D%5D%7D\n```\n\n</details>\n\n### Manual\n\n```bash\n# Homebrew\nbrew install kubeleash/tap/kubeleash\n\n# Go\ngo install github.com/kubeleash/kubeleash/cmd/kubeleash@latest\n\n# Container (great for running the MCP server sandboxed)\ndocker run --rm -i -v ~/.kube:/root/.kube:ro -v ./policy.yaml:/policy.yaml:ro \\\n  ghcr.io/kubeleash/kubeleash --policy /policy.yaml\n```\n\n> kubeleash runs **locally over stdio** and talks only to your clusters. There\n> is intentionally **no remote/hosted URL connector** — it would mean handing\n> your cluster credentials to a third party.\n\n## Use it as an MCP server\n\nkubeleash exposes 8 generic, GVK-agnostic tools (`k8s_list`, `k8s_get`,\n`k8s_apply`, `k8s_delete`, `k8s_logs`, `k8s_exec`, `k8s_scale`, and\n`k8s_capabilities`) that work for any resource, including CRDs. Every call is\nchecked against your policy and recorded to a JSON audit log on stderr (stdout\nis the MCP transport). It speaks MCP over stdio — point your client at the\nbinary (or container):\n\n```jsonc\n// Claude Desktop / Cursor / VS Code MCP config\n{\n  \"mcpServers\": {\n    \"kubeleash\": {\n      \"command\": \"kubeleash\",\n      \"args\": [\"--policy\", \"/absolute/path/to/policy.yaml\"],\n      \"env\": { \"KUBECONFIG\": \"/absolute/path/to/kubeconfig\" }\n    }\n  }\n}\n```\n\n## Privacy\n\n**Zero telemetry. No phone-home. Local-only by design.** kubeleash talks only to\nthe Kubernetes API servers you point it at — there is intentionally no remote or\nhosted connector to route your cluster credentials through. That's a feature, not\na gap: you run it against real clusters with privileged credentials, so nothing\nshould sit between the agent and your API server but the leash.\n\n## Project\n\n- [Design](docs/design.md) · [Contributing](CONTRIBUTING.md) ·\n  [Security & threat model](SECURITY.md) · [Code of Conduct](CODE_OF_CONDUCT.md)\n- License: [Apache-2.0](LICENSE)\n",
  "bytes": 10017,
  "sha": "b1c5763a578b60f389db2e06437389c04219b282dd9b9659a9bc9f3d6d55e45a",
  "repo_slug": "kubeleash/kubeleash",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_kubeleash_kubeleash_79ed8f4d/readme"
}