AI agents

Kubyl is an ACP client, like Zed. It starts the AI agent you already have (Claude, Codex, Gemini CLI, GitHub Copilot, or any agent that speaks the Agent Client Protocol), shows the conversation in a panel and gives the agent tools to read the cluster. Kubyl holds no API keys and pays for nothing: the agent signs in on its own and talks to its own provider.

Supported agents#

Kubyl looks for these programs on your login shell's PATH and in the usual install folders (npm global, Homebrew, ~/.local/bin). Kubyl never installs or downloads an agent. If none is found, the panel shows the install commands to copy.

Set up and sign in#

1. Install an agent from the table above.
2. Sign in once in a terminal, for example claude, codex login, gemini, copilot followed by /login. If an agent offers its own sign-in methods over ACP, the panel shows a button per method. When an agent needs a sign-in, the panel says so and has a Retry button.
3. Open the panel with Ctrl ? (View: Agent Panel), pick the agent and start a thread. A thread is bound to the cluster that is active when it starts and shows the cluster's color dot. Switching clusters starts a new thread.

A crashed agent shows its last error output, a Retry button and Agent: Show Agent Output. The first time, the panel shows a note about what the agent can see, which you can dismiss.

Using the panel#

• Ask about a selection. Press Shift A on a resource (Resource: Ask Agent). Kubyl attaches a masked description of the object as a chip and starts a thread. The same works on selected log lines, on the events the Events panel shows (at most 60), on an alert and on an Argo CD application.
• Mention resources. Type @ in the input to attach objects of the thread's cluster from Kubyl's loaded caches.
• Tool-call cards. Every call the agent makes to Kubyl's tools shows as a card naming the object it read, so you can see exactly what went to the agent.
• Session settings. The model, thinking level, mode and other settings the agent offers appear as dropdowns and toggles. The thread header shows how much of the context is used (yellow from 80 %, red from 95 %).
• Plans, questions and files. Plans, forms and links the agent asks for, and changes to files in its folder, are shown in the thread.
• Status. The status bar shows an item while an agent works or waits for you, and a toast tells you when a turn ends while Kubyl is not focused.

Other palette actions: Agent: New Thread and Agent: Show Agent Output.

What the agent can do#

The agent gets one MCP server per thread, called kubyl. Every tool works on the thread's cluster only, uses your RBAC through your own connection, and returns at most 64 KiB (agent.max_tool_output_kib).

Consent and permission prompts#

• Kubyl's own tools never prompt. They are read-only and masked.
• Commands. When an agent wants to run a shell command, Kubyl runs it locally and shows it with its working folder and environment changes. Every command needs your approval, and a command that sets environment variables always asks (an attempt to replace KUBECONFIG is dropped with a warning). Commands that read kubeconfigs or Secrets (kubectl get secret, cat ~/.kube/*, kubectl config view --raw and similar) get a warning line. Their output is scrubbed before it goes back to the agent.
• Files. The agent may read inside its thread folder. Reads outside it and every write ask first, and writes show as a diff.
• Questions. Forms the agent asks are shown in the thread. A link the agent wants to open is shown with its URL and opens in your browser only after you confirm.
• Allow always is remembered for that thread only.
• Permission modes. If the agent offers a mode such as "Bypass permissions" you can pick it. That only stops the agent's own prompts. Commands run through Kubyl and file changes still ask.

Security notes#

• Masking. Secret data and stringData, Helm release Secrets and ConfigMaps, inline route TLS keys, managedFields and string values under credential-like keys (password, apiKey, authToken…) never leave Kubyl unmasked. There is no tool, setting or prompt that reveals them to the agent. Tokens, JWTs, bearer headers and PEM private keys found in logs, events and annotations are replaced with dots on a best-effort basis.
• Logs go as they are. Masking of free text is a safety net, not a guarantee. A value under an unusual key name in a custom resource can still reach the agent. Everything the agent reads goes to its provider.
• The agent is not sandboxed. It runs as you and can read files such as ~/.kube/config with its own tools. Kubyl covers what goes through Kubyl.
• No kube token. The agent never receives your token. Its KUBECONFIG points to an empty file, so kubectl in the agent's own shell reaches nothing, unless you set agent.kubectl to context.
• Local only. The MCP endpoint listens on 127.0.0.1 with a random per-thread bearer token held in memory. Agents that cannot use HTTP get a stdio bridge, kubyl mcp-bridge, which is the Kubyl binary itself.
• Nothing is logged or stored. Prompts, tool results and agent stderr are not logged. state.json keeps only the agent, cluster, title, folder and session id of each thread, never the transcript. A closed thread can be reopened only if the agent supports loading sessions; otherwise it is gone.
• Prompt injection. Logs, annotations and custom resource fields can contain text written by someone else that the agent reads. Because the agent has no write tools in Kubyl, this cannot change your cluster through Kubyl, but treat what the agent suggests with care.

Settings#

All keys live under agent in settings.json. See Settings.

{
  "agent": {
    "default": "claude",
    "custom": [{ "id": "mine", "name": "Mine", "command": "mine-acp", "args": ["--acp"] }],
    "kubectl": "none"
  }
}

Ask about any resource#

Besides Ask Agent, resources offer ready-made questions. They appear as Ask: … entries in a list row's context menu, in the palette's > mode and as buttons in an Ask agent section of the details panel. They are hidden while no agent is installed.

• Nothing is sent until you press Enter. A click only opens the panel with the question in the composer, so it costs no tokens and you can edit it first.
• No data in the question. It names only the cluster, kind, namespace and name of the object, and the read-only tools to use. The agent reads the rest itself through the tools, so masking applies. Asking about a Secret sends no values.
• Every question tells the agent to use read-only tools only, change nothing and keep the answer short.