The AI agent
Run Claude Code or Codex in a panel wired to the cluster you are looking at — with read tools, four mutations, and an approval dialog in front of every change.
kdashboard does not ship a model, hold an API key or run a service. The agent panel runs the agent CLI you already have, in a real terminal, and gives it one door to the cluster: a set of tools served by kdashboard on 127.0.0.1. Those tools use your kubeconfig credentials, so the agent can never do more than you can.
What your CLI sends to its own provider is governed by that provider’s terms, not by kdashboard.
What you need
One of these, installed and logged in, on your PATH:
| CLI | Command | Install |
|---|---|---|
| Claude Code | claude | code.claude.com/docs |
| Codex CLI | codex, 0.100 or newer | developers.openai.com/codex/cli |
If kdashboard cannot find it, the panel says so and links the install page. An older codex still starts, with a warning that it may not speak MCP over HTTP.
Start a session
- Press ⌘J, or click the agent button in the status bar. The panel opens at the bottom; drag its top edge to resize it.
- Choose the CLI in the Agent menu, if you have both.
- Click Start, and type your question.
| Button | Effect |
|---|---|
| Start / Restart | A new conversation |
| Resume | Continues the last conversation you had in kdashboard |
| Stop | Ends the session |
| Hide | Closes the panel. The session keeps running; the status bar shows a green dot. |
One session runs at a time, and it is pinned to the context it started on. Switch context and the session ends — an agent must never carry on against a different cluster than the one you were looking at.
Let kdashboard write the question
Prompts
The Prompts menu in the panel header starts a session with a ready-made task: Cluster health check, Namespace health check (when a namespace is selected), Review warning events, Rightsizing review and Node capacity & pressure.
Quick actions
Right-click any row. The actions that start with Agent: open the panel with a prompt already pointed at that resource:
| Action | On |
|---|---|
| Analyze Logs, Why Is It Crashing? | Pods |
| Optimize Resources | Deployments, StatefulSets, DaemonSets |
| Diagnose Rollout | Deployments, StatefulSets, DaemonSets, ReplicaSets |
| Why Did It Fail? | Jobs, CronJobs |
| Diagnose Node | Nodes |
| Check Connectivity | Services, Ingresses, Endpoints, NetworkPolicies |
| Why Is It Pending? | PersistentVolumeClaims |
| Why Isn’t It Scaling? | HPA, VPA, WPA |
| Explain This Resource, Ask Agent About This… | Everything |
Investigate with agent
The same hand-off is available where you already have a diagnosis: on the selected problem (and Investigate all with agent for every problem), on an alert, and in the log viewer, which passes along your filter and level.
If a session is already running, the prompt is typed into it and left for you to review and send. Otherwise a new session starts with it.
What the agent can do
Read
| Tool | Returns |
|---|---|
get_current_context | The context, the API server and the namespaces you can see |
list_resources | Any kind, optionally in one namespace |
get_resource | One object, as YAML |
get_pod_logs | Logs, with container, previous, tailLines, sinceSeconds and grep |
list_events | Events of a namespace or an object, newest first |
top_pods, top_nodes | Live usage from metrics-server |
list_problems | The same scan as the Problems view |
get_rightsizing | Requests against real usage |
query_prometheus | A PromQL range query, if you configured a Prometheus |
Lists are capped at 200 items, log reads at 2,000 lines (5,000 when grepping) and Prometheus answers at 50 series, so a large cluster cannot flood the conversation.
Change
Four tools, and nothing else:
| Tool | Does |
|---|---|
scale_workload | Sets the replicas of a Deployment, StatefulSet or ReplicaSet |
restart_rollout | Restarts a Deployment, StatefulSet or DaemonSet |
delete_pod | Deletes one pod, so that its controller recreates it |
update_container_resources | Sets the requests and limits of one container |
The agent cannot create or apply manifests, delete anything other than a pod, exec into containers, forward ports, or cordon and drain nodes.
Approvals
Every change stops at a dialog, Agent requests a change, which names the tool, the context, the resource and the exact change — replicas → 5. Nothing happens until you click Approve.
- Deny, Esc, clicking outside the dialog, or five minutes without an answer all count as no. The agent is told you declined and not to retry.
- While a request waits, the panel shows APPROVAL PENDING and the status-bar button turns amber — also when the panel is hidden.
- If you switch context while a dialog is open, the change is not applied even if you approve it.
You can turn approvals off in Settings → General → AI Agent → Require approval for agent mutations. The agent can then change the cluster without asking. Only do that on clusters where that is acceptable.
Where it runs
The CLI runs in ~/.kdashboard/agent-workspace, an empty folder — never inside one of your projects. Using the same folder every time is what makes Resume work. It is safe to delete.
The endpoint the agent talks to listens on 127.0.0.1 only, on a random port, behind a token generated for that session, and exists only while the session runs.
To use the same tools from Claude Desktop, Cursor or another client, see MCP server.