paseo plugin add jeroenfrenken/paseo-k8s\n\n\nRequires Paseo >= 0.8.0. v0.8 split plugins into separate client and server\nruntime entries; this plugin is migrated to that layout and declares\n
\nrequirements.paseoin its manifest, so an older Paseo will refuse to load it.\nThe last version that ran on 0.7.x is taggedv0.7-final.
Or from a local clone:
\ngit clone git@github.com:jeroenfrenken/paseo-k8s.git\ncd paseo-k8s && npm install\npaseo plugin install \"$PWD\"\nOnce installed, pick it up later with:
\npaseo plugin status k8s # is there a newer commit?\npaseo plugin update k8s # pull it in\npaseo plugin logs k8s # what the plugin printed\nNothing is configured out of the box: on first run the panel offers any kubeconfig\nit discovers, checks which command-line tools are present, and takes you to\nSettings to add a cluster.
","readmeText":"# Kubernetes panel (Paseo plugin)\n\nAdds a **Kubernetes** item to the Paseo sidebar — its own global surface, below the\nbuilt-in items, not attached to a workspace or agent chat. Add as many clusters as\nyou like and switch between them from the header.\n\n## Install\n\n```sh\npaseo plugin add jeroenfrenken/paseo-k8s\n```\n\n> **Requires Paseo >= 0.8.0.** v0.8 split plugins into separate client and server\n> runtime entries; this plugin is migrated to that layout and declares\n> `requirements.paseo` in its manifest, so an older Paseo will refuse to load it.\n> The last version that ran on 0.7.x is tagged `v0.7-final`.\n\nOr from a local clone:\n\n```sh\ngit clone git@github.com:jeroenfrenken/paseo-k8s.git\ncd paseo-k8s && npm install\npaseo plugin install \"$PWD\"\n```\n\nOnce installed, pick it up later with:\n\n```sh\npaseo plugin status k8s # is there a newer commit?\npaseo plugin update k8s # pull it in\npaseo plugin logs k8s # what the plugin printed\n```\n\nNothing is configured out of the box: on first run the panel offers any kubeconfig\nit discovers, checks which command-line tools are present, and takes you to\nSettings to add a cluster.\n\n## What it shows\n\nA Lens-style workspace built inside the one surface the host gives a plugin.\n\n**Header** — a cluster dropdown naming the current cluster and its context, then\nrefresh, auto-refresh, Shell and Settings. Production clusters carry a red\n`PRODUCTION` badge. Below it, the live context and API server.\n\n**Tabs** — open as many resource views as you like. `+` opens a full picker showing\nevery view with its live count; `×` closes a tab. The **namespace dropdown** sits on\nthe same line as the tabs, on the right, and is searchable.\n\n**First run** — with no cluster configured yet, the panel opens on a setup screen\nthat lists any kubeconfig it discovered, checks which command-line tools are\ninstalled, and links straight into Settings.\n\n## Command-line tools\n\nNothing needs to be installed to browse a cluster: that path talks to the API\nserver over HTTPS directly. The setup screen and **Settings → Command bar** both\nshow what is present and what each one unlocks:\n\n| Tool | | Unlocks |\n|---|---|---|\n| `kubectl` | recommended | The command bar, and the Flux reconcile/suspend buttons |\n| `git` | optional | Comparing the deployed revision to a local Flux checkout |\n| `helm` | optional | Running helm from the command bar |\n| `flux` | optional | Nothing the panel needs — Flux state is read from the API. Only for running `flux` in the command bar |\n\nMissing tools show an install hint rather than blocking anything.\n\n**Settings** — its own screen with a sidebar:\n\n- **Clusters** — add and remove as many as you like. There is no fixed set of\n environments: each cluster is a name, a kubeconfig, a context, a default\n namespace, and a *production* flag that turns it red everywhere. Ids are slugged\n from the name and kept unique. Each has a connection test.\n- **Command bar** — how commands run, the allowed programs, and the timeout.\n- **GitOps** — the Flux repo path.\n- **Config file** — where all of this is stored, and how to point at another file.\n\n**List view** — a dense sortable table per tab. Click any column header to sort\n(again to reverse). A search box filters as you type across name, namespace, status,\nnode and image. Live **CPU and memory** columns come from metrics-server; they are\nhidden automatically when it is not installed. The footer shows matched/total counts.\n\n**Detail drawer** — click a row. Opens on the right (stacked below on narrow\nwindows) with stat tiles, a replica or capacity meter, full properties, the owning\nworkload's pods, and one-click actions that push a prefilled command into the shell\n(`describe`, `get -o yaml`, `rollout status`, `top`, `events`).\n\n**Bottom dock** — resizable by dragging its handle, collapsible, with its own tabs:\n\n- **Log tabs** — one per pod, several open at once. 100/500/2000 line tail, container\n picker on multi-container pods, a **Previous** toggle on pods that have restarted\n (reads the terminated container), **Follow** for 5s polling, and a search box that\n filters the lines. Timestamps render as wall-clock time.\n- **Shell tab** — type kubectl commands with `KUBECONFIG` already pointed at the\n selected environment. Up/down arrows walk history. One status line shows the\n cluster, namespace and what may run; everything configurable lives in Settings,\n reachable from the ⚙ in the tab's own header. See *Command bar* below.\n\n**Overview tab** — replica availability as the headline figure, stat tiles, a\npods-by-phase bar, and per-node CPU/memory pressure meters.\n\n**Flux tab** — see *GitOps* below.\n\nHealth is always carried by a glyph and a word as well as a colour\n(`● Healthy`, `▲ Progressing`, `◆ Degraded`, `■ Down`, `○ Idle`), so nothing depends\non hue alone.\n\n## GitOps (Flux)\n\nThe **Flux** tab reads the cluster's Flux state directly — it is cluster-wide and\ndeliberately ignores the namespace filter.\n\n- **Deployed revision** as the headline: the git revision every Kustomization has\n applied, e.g. `main@1a2b3c4`.\n- **Local comparison.** If a checkout of the GitOps repo is found, the panel says\n whether your branch is in sync or lists the commits the cluster has not applied\n yet. It is strictly read-only: it never fetches and never touches the working\n tree. If the deployed commit is not in your clone it says so and suggests\n `git fetch` rather than running one.\n- **Sources, Kustomizations, Helm releases** with ready / failed / suspended state,\n the path or chart each came from, applied revision, and the condition message.\n- **Image automation** — ImagePolicies with the newest image they resolve to. When\n that differs from what the workload is actually running, the row is flagged\n **update pending** with `running … → latest …`.\n- **Actions** on any row: **Reconcile**, and **Suspend**/**Resume** for the kinds\n that support it.\n\nActions run through `kubectl` on the command-bar path rather than a raw API PATCH,\nso they inherit the allowlist and show up as a normal command. `Reconcile` only sets\nthe standard `reconcile.fluxcd.io/requestedAt` annotation; suspend/resume patch\n`spec.suspend`. Nothing else is ever written.\n\nThe repo is found at `PASEO_K8S_FLUX_REPO`, then `fluxRepoPath` in clusters.json,\nthen `~/flux`. Saving clusters from the UI preserves `fluxRepoPath`.\n\n## Attaching cluster context to an agent\n\nThe plugin registers a **Kubernetes** composer attachment source. In an agent's\ncomposer, attach → Kubernetes → search, and the picked resource arrives as context:\n\n- **A pod** — phase and reason, container readiness, restarts, node, CPU/memory,\n its recent warning events, and its last 80 log lines.\n- **A workload** — replica counts, health, condition message, images, every pod with\n its status, the warning events across them, **and a log tail from each of up to four\n of its pods**, so asking about \"the api pods\" gets all of them rather\n than one. Running pods are preferred over finished ones (completed Jobs and\n migrations sort last).\n\nBoth environments are searched at once and each result is labelled Staging or\nProduction. Unhealthy resources are ranked first, since a broken pod is usually the\none you meant to ask about. Cluster listings are cached for 20s so typing in the\npicker does not hammer the API; logs are fetched live for the results actually shown.\n\n## Launching an agent from a resource\n\nSelecting a pod, workload or node puts an **✦ Ask an agent** button at the top of\nthe detail drawer. It opens an inline panel with an editable instruction, a project\npicker and a model picker, and starts a new Paseo agent whose opening prompt is your\ninstruction followed by the same live context bundle the attachment picker builds —\nstatus, events and log tail for a pod; replicas, images, pods and events for a\nworkload; pressure and scheduled pods for a node.\n\n**A fresh workspace is always created**, never reused. Pick the project it belongs\nto and whether it is a **Worktree** (branch-off, the default) or a plain **Local**\ndirectory. Non-git projects only offer Local, and the panel says why.\n\nThe agent is created inside that new workspace and tagged with labels\n`source=k8s-plugin`, `environment` and `resource`, so agents started this way are\neasy to find later.\n\nThe panel reads the daemon's provider catalogue, so **Agent** lists every provider\nthat is enabled and available (Claude, Codex, OpenCode, Cursor, …) and **Model**\nlists that provider's models, with its default preselected. Providers that report\nno models are left out rather than offered as dead entries.\n\n## Command bar\n\nThe shell tab runs commands on the daemon with `KUBECONFIG` set to the selected\nenvironment's kubeconfig. It is **not** a PTY — the host's plugin API exposes no\nterminal, so `kubectl exec -it` and anything else needing a TTY will not work. One\ncommand in, its output back.\n\nThe shell tab is only a shell: you type, it runs. *How* it runs is decided once in\n**Settings → Command bar**, which offers two clearly described modes:\n\n- **Allowlist only** (default, recommended) — the first word must be one of the\n programs you listed (`kubectl`, `helm`, `kustomize` out of the box). The line is\n split into arguments directly, without a shell, so quoting tricks and injection\n cannot happen. Pipes, redirects and wildcards are refused, with a message saying\n which setting to change.\n- **Full bash** — the whole line goes to `bash -lc`. Pipes, redirects and wildcards\n work and anything on your PATH can run, including things that delete. Marked\n *less safe* in Settings, and the shell tab's header says **▲ Full bash** while it\n is active.\n\nThe shell header always states the current mode and links straight to the setting.\nOutput is capped at 400 KB per stream.\n\nFlux actions ignore this setting entirely: they are fixed `kubectl` calls, pinned to\nallowlist mode with `kubectl` as the only permitted program.\n\n## Configuration\n\nThe panel talks to the Kubernetes API directly over HTTPS using a kubeconfig per\nenvironment. Open **Clusters** in the header to set them.\n\nConfig lives at `~/.config/paseo-k8s/clusters.json`:\n\n```json\n{\n \"environments\": [\n {\n \"id\": \"staging\",\n \"label\": \"Staging\",\n \"kubeconfig\": \"/home/you/.config/kubernetes-mcp/staging.kubeconfig\",\n \"context\": null,\n \"namespace\": null\n },\n {\n \"id\": \"prod\",\n \"label\": \"Production\",\n \"kubeconfig\": \"/home/you/.config/kubernetes-mcp/prod.kubeconfig\",\n \"context\": null,\n \"namespace\": \"app\"\n }\n ]\n}\n```\n\n- `kubeconfig` — path to a kubeconfig file. `~` is expanded.\n- `context` — which context inside that file; `null` uses `current-context`.\n The Clusters editor lists the contexts it finds in the file so you can pick one.\n- `namespace` — the namespace the panel opens on; `null` means all namespaces.\n\n**Pointing at a file elsewhere.** The Clusters section has a *Use a config file\nelsewhere* field: give it a path to another `clusters.json` (or a directory\ncontaining one) and the panel reads and writes that file from then on. The pointer\nis stored in `~/.config/paseo-k8s/pointer.json`; *Use default* clears it.\n`PASEO_K8S_CONFIG` overrides both.\n\n**Before any config exists** the panel discovers kubeconfigs on its own: it reads\n`kubeconfig = \"...\"` out of `~/.config/kubernetes-mcp/{staging,prod}.toml` (the\n`kubernetes-mcp-server` configs behind the `k8s-staging` / `k8s-prod` MCP servers),\nthen falls back to `~/.config/kubernetes-mcp/