AI agents¶

An AI agent such as Claude Code or Cursor can work on your clusters through kubelatch's MCP server. It connects to one address, you authorize it in your browser, and it acts as you with only the permissions you choose, for a few hours. kubelatch records every call it makes, can hold its changes until you approve them, and lets you cut it off at any moment.

Why not give it your kubeconfig¶

Say you're developer on shop and you ask your agent "find out why the web pod is failing". Without kubelatch you have two bad options: give it your kubeconfig, and it can do everything you can while the audit log shows only you; or ask an administrator for a bot and wait, which nobody does for a ten-minute task.

kubelatch adds a third: you authorize the agent yourself. It's the gesture of Sign in with Google: you don't hand over your password, you give a limited permission you can take back.

Connect your agent¶

1. Once, add kubelatch to your agent. On Home, Connect an agent shows the command with your kubelatch's address. For Claude Code:

   claude mcp add --transport http kubelatch https://kubelatch.example.com/mcp
   

   For Cursor, in .cursor/mcp.json:

   {
     "mcpServers": {
       "kubelatch": {
         "url": "https://kubelatch.example.com/mcp"
       }
     }
   }
   

   Any other MCP client: Streamable HTTP at that address; it signs in with OAuth. With Claude Code you can install the plugin instead, which adds the server and the rules for the agent.

2. The first time the agent uses kubelatch, your browser opens on kubelatch, where you're already signed in (if not, sign in and it brings you back).

3. You see Let Claude Code act as you? (with the agent's name), over Who asks: the Agent, the site the browser Returns to after you answer, and how long the request lasts. Under What it gets · until when are your permissions, grouped by cluster. For each one, choose what the agent gets with the three buttons beside it: Leave out, Read only (viewer) or Same role (…); All read only and All as me (no cluster-admin) set them all at once. Under them, Permissions you get later has the same three buttons (Leave out, Read only (viewer) and Same role), set to Read only (viewer); All read only and All as me (no cluster-admin) set it too. Then the Duration (8 h unless your administrators changed it) and whether Writes need my approval (on). A sentence above the buttons sums it up, for example "Claude Code acts as you with 2 permissions for 8 h, and what you get later as read only; each write waits for your approval." Click Authorize.
4. The browser tells you Authorized. Go back to the agent. The agent carries on.

On that page:

• Read only (viewer) is offered, and chosen for you, only for a permission whose role includes viewer without being it: developer, admin and cluster-admin. A viewer permission comes as Same role (viewer), chosen for you. A debugger or secrets-reader permission, or one of a custom role, can only be passed as itself, and it comes set to Leave out: choose Same role (…) only if the agent needs it. You include at least one permission.
• cluster-admin can only be passed as Read only (viewer): an agent never inherits cluster-admin.
• A name the agent gives itself is marked unverified: kubelatch has not checked it. An agent that publishes its identity shows published by …, with the site that publishes it.
• The line right above the buttons says where your answer goes. For an agent that only returns to your own computer it is This agent runs on your computer. Authorize it only if you just connected it yourself.; for one that has other addresses but returns to this computer this time, This agent gets your answer at …, on this computer. Authorize it only if you just connected it yourself. Both are quiet reminders. Any answer that goes anywhere else raises a highlighted warning: This agent gets your answer at …, off this computer. Authorize it only if you know that address and just connected the agent yourself., or, when it goes to an app that opens its own links (such as cursor://), This agent gets your answer through whatever app opens … links on this computer, and that app can pass it on. Authorize it only if you just connected the agent yourself from that app. If you didn't just connect one, click Deny. Which addresses an agent may use is in Signing in (delegated agents).
• If the time runs out before you answer, the buttons give way to This consent no longer works: go back to the agent and connect it again.
• A permission you hold in two ways, directly and through a group, is one row, marked via group … when a group gives it, as in My access. Your choice applies to every way behind the row.
• Permissions you get later is what happens when you receive a permission after authorizing the agent, directly, in a batch or by joining a group. Read only (viewer) gives the agent viewer there, Same role the same role, and Leave out nothing. The agent has it from its next call, without connecting again, and loses it when the session or your permission ends. Read only applies only to a role that includes viewer; a debugger, secrets-reader or custom-role permission you get later passes only with Same role; and cluster-admin never passes as itself, but as viewer. The session's page shows your choice as Later permissions.

What the agent sees and does¶

• Clusters see you, user:<your login>, but only with the permissions you gave the agent. What its role doesn't allow, the cluster refuses with a 403, even though you could do it.
• It has tools to read (list objects, read one, logs, events, Secret values), to change (apply an object, delete one, scale, restart a rollout) and to ask for more access. MCP server lists them. Every agent sees the tools that change things, whatever its role: a change its role doesn't allow gets the cluster's 403, and it can ask you for more with request_access (see below).
• Secret values stay hidden unless the agent asks for them on purpose, and each such read is recorded.
• Ask it to call whoami to see what it can do, where, and until when.
• You follow what it did in Agents: each session has a timeline with every call. If an administrator looks at the audit log, your agent's requests show as yours, through the agent.

What it will ask you to approve¶

When you include a role that writes, such as Same role (developer), and keep Writes need my approval on, every change the agent wants waits for you, and you see it before it happens:

1. The agent gives you a link, https://kubelatch.example.com/agents/requests/…. Agents in the sidebar shows how many approvals wait for you, and so does the bell, which opens the approval itself when only one waits.
2. The page is titled with the change in a sentence (for example "deploy-bot wants to change configmaps/feature-flags in apps (kind-local)") and says who asked and how long is left. A line sums up what the change does ("Changes 2 lines of data"), and Changes shows the object now against what the cluster says it will become, lines that go with − and lines that come with +. The metadata the server manages comes folded. Secret values stay hidden, and one the write changes reads <redacted, N bytes, changed>.
3. Click Approve or Deny; on a phone the two buttons stay at the foot of the screen. Each asks you to confirm with the sentence of the change. Once approved, the write runs once, exactly as you saw it. The page then says what became of it: "Approved by alex at 17:21 · ran once, the cluster answered 201."

You often don't have to carry the link. A client that can ask, such as Claude Code (its default runtime since 2.1.274, with no plugin), shows the change in a sentence and asks to open the approval page in your browser. Accept, decide there, and the agent's call goes on by itself and returns the result, whose first line says "approved by alex at …". The call waits for your decision for about a minute, then asks again; the approval stays open. If you decline the question, or the agent runs without one (claude -p), or its client can't ask, the agent gives you the link in text and calls again with the approval_id once you've decided; that call waits for you as well.

In Agents, a pending approval also has Approve on its row. It asks the same confirmation as the page, with the sentence, what the change does and the time left, so you can approve without opening the page. Open it to read the whole diff first.

A write waits 15 minutes for you; once approved, the agent has 15 minutes to run it.

For a task with several changes, the agent can ask for a role for a while instead, for example developer on shop for 30 minutes. You approve it on the same kind of page; while it lasts, the agent's writes there don't ask you one by one. It can ask only for a role you hold on that cluster and namespace, never cluster-admin, for at most 8 hours.

How much it bothers you: the browser opens once per session, like kubelatch login. Read-only work asks nothing.

Cut it off¶

The session ends by itself when its duration runs out. Before that, in Agents, open the session and click Cut: its tokens are revoked, its pending approvals are closed, and the permissions you gave it end. Its next call fails. Connecting it again asks you again.

If one of your permissions is revoked or expires, the agent loses what came from it at once.

Your team's agents¶

An agent that isn't yours, such as an on-call agent that reviews alerts at night, uses a bot that an administrator creates, with the permissions the administrator grants it (AI agents for administrators). It and your own agent don't touch: your Claude Code acting as you, read-only, and bot:ops-agent, viewer on every namespace, are two identities.

The Claude Code plugin¶

The plugin kubelatch adds kubelatch to Claude Code together with the rules that make it use kubelatch:

claude plugin marketplace add picaportelabs/kubelatch
claude plugin install kubelatch@kubelatch

When the plugin is enabled, Claude Code asks for kubelatch URL: your kubelatch's address, such as https://kubelatch.example.com, without /mcp. You can change it later in /config. Then the agent signs in as in Connect your agent. Don't also add the server with claude mcp add: the agent would see it twice.

The plugin brings:

• the kubelatch MCP server;
• the skill kubernetes-via-kubelatch: use kubelatch's tools for everything on Kubernetes, start with whoami, a 403 is an answer, and how approvals go;
• a hook that refuses kubectl, helm and k9s commands that reach a cluster, and kustomize build | kubectl, and tells the agent which tool to use instead. Commands that don't reach a cluster, such as helm template, kustomize build or kubectl kustomize, still work.

For other agents, the same rules are in integrations/rules/: paste kubernetes-via-kubelatch.md into your project's AGENTS.md (Claude Code reads AGENTS.md only when there's no CLAUDE.md; otherwise paste it into CLAUDE.md), or copy kubelatch.mdc to .cursor/rules/ for Cursor.