Skip to content

AI Copilot + Mobula

A cluster-grounded assistant in a global dock that answers questions by navigating Mobula, KubeManta's live model of your cluster, and cites the actual resources its answers come from.

Tier: Free — some features Pro

What it does

The AI Copilot is an assistant that lives in a global dock on the right of every screen. It answers questions about your cluster by reading Mobula — KubeManta's live model of what exists in your cluster, how it is connected, and what is currently wrong with it. Because answers come from Mobula rather than a generic prompt, they cite the actual resources they were derived from, and you can click a citation to jump straight to that resource.

The structural Mobula surface (/graph/*) is Free and works with AI disabled entirely — it is deterministic Kubernetes/DB topology, the same data behind the free Cluster and Network panels. The Copilot chat itself is Pro: Free installs get a small daily limit on chat, which a licence lifts. A separate per-viewer daily AI cap applies on every tier — see Setup.

Mobula

Mobula is assembled from the signals KubeManta already collects — workload topology, failure cascades, network paths, resource relationships, health signals, and container-scanning results — together with KubeManta's own operational memory, such as the audit trail, past diagnoses, and alert history. The result is one connected picture of the cluster rather than a pile of separate views: an alert, the pod it fired on, the workload that owns it, the node it landed on, and the finding against its image are all reachable from one another.

Two properties matter operationally. It is built on demand — there is no graph database to run, scale, or back up, and nothing to keep in sync, because Mobula is assembled per request from live cluster state. And it respects your boundaries — namespace allowlists, system-namespace hiding, and secret redaction apply to Mobula exactly as they do everywhere else in the product. The same model powers the Mobula cluster map in the UI and grounds the Copilot's answers.

The Mobula API — GET /graph/subgraph?focus=&hops=&budget= for a token-budgeted subgraph around a focus node, and GET /graph/entity/{id} for node detail plus a deep-link to the relevant UI view — requires authentication only, not an AI entitlement or license. Both exclude AI-derived memory nodes and respect the namespace allowlist, system-namespace hiding, and redaction.

How the Copilot retrieves context

When you chat with the Copilot it navigates Mobula — following the connections around whatever you asked about — instead of dumping the whole cluster into the prompt. In practice, a question about one failing pod pulls in that pod's events, its owner, its recent findings, and little else. Retrieval is bounded by design: it walks a limited distance from the starting point and works to a token budget, so a question about one workload cannot quietly turn into a cluster-wide scrape. Every step re-checks namespace scope against AI Guardrails — an out-of-scope target returns an error, never raw data — and any log content is redacted before the model sees it. The same read-only retrieval is available to external agents through the MCP server.

MCP server — connecting an external agent

KubeManta is a Model Context Protocol server, so an agent you already use — Claude Code, or anything else that speaks MCP — can read this cluster directly. It talks the protocol over Streamable HTTP at https://<your-host>/api/agent/mcp, and the MCP server section of Admin → AI is where you set it up: it shows the endpoint filled in with your own host, a copyable claude mcp add command, the exact list of tools your install advertises, and the reasons a connection would currently fail.

Which clients can connect. Both kinds now. A client that can send a header — Claude Code is the tested path — authenticates with a per-user API key. A client that speaks OAuth, which includes Claude Desktop's custom connectors and claude.ai, registers itself and runs an authorization-code flow: it discovers our metadata, you approve it on a consent screen naming the client, and it receives a token.

An OAuth token is your account, not a new identity. It carries no role of its own — it sees exactly what you see, demotes when you are demoted, and dies when your account is deactivated. It is read-only, bound to this server (a token minted for a different MCP server is refused here), expires after an hour, and is revocable at any time from Account → Connected apps. Every call it makes is audited by tool name, exactly like a key.

For the header path, the credential is a per-user API key you mint yourself under Account → API keys — an admin can list and revoke another user's keys, but cannot mint one on their behalf. The key carries its owner's role, which is what makes it safe to hand to a tool: a viewer's key is read-only, and revoking the key, deactivating its owner or demoting them to viewer each take effect on the next request. There is no separate MCP credential to remember or clean up.

What an external agent gets is deliberately narrower than what the in-product Copilot gets, and it is bounded by the same controls rather than a second policy of its own. The surface is read-only — write tools and pod exec are not exposed on it at all — every result crosses the same redaction boundary before leaving the server, namespace scope and the allow/deny lists apply unchanged, and each call is written to the audit trail naming the tool that was used rather than merely recording that something was read. A tool you deny in AI Guardrails disappears from the advertised list and is refused if called, so an agent is never offered a capability it cannot use.

The MCP section carries its own kill switch, separate from the AI kill switch alongside it. One toggle closes the surface: every request is refused with 403 mcp_disabled, on the protocol endpoint and the older REST pair alike, and the page shows it as the first reason a client would fail. It exists because MCP is the one surface that hands a non-interactive external process cluster-wide reads — an admin needs to be able to close that in one action, without waiting for a redeploy, revoking keys one at a time, or turning off AI for everyone. Both directions are audited; turning it back on is the event worth reviewing. API keys cannot flip it, so a leaked key cannot re-open a surface an admin closed.

MCP is available on every tier, including Free. What keeps that safe is not the licence: the MCP surface exposes an explicit allowlist of read-only tools and refuses anything outside it, so no plan has ever been able to write through MCP. A caller still sees only the namespaces they are entitled to, and results are redacted on the way out. The AI kill switch applies separately: with AI disabled an agent can still list the tools but every call is refused.

AI Context

The AI Context feature (reached from the WORKSPACE group in the sidebar, on admin accounts only) is an operator-curated markdown knowledge base — org runbooks, conventions, escalation paths — that the AI retrieves on demand via a search tool instead of re-deriving them every conversation. Retrieval is token-cheap keyword search: the AI searches, then pulls the full text of only the doc it needs. CRUD is admin-gated, and docs are capped in size and count so the knowledge base stays prompt-friendly.

Standing instructions — a doc the AI obeys, not just reads

Marking a doc include in AI does more than make it searchable: its contents are attached to every AI run — the Copilot, namespace Diagnose, and the AI SRE Report — as standing context.

That makes it the place to record what your cluster's normal looks like. If a document says "Disregard quay-pull-secret pod errors", the AI is instructed to stop raising it, and to say so rather than going quiet:

quay-pull-secret disregarded based on AI Context file MIND.md

Two things about that are deliberate.

It is an instruction, not a filter. The AI is told to obey the document; it is not a rule enforced outside the model, so treat it as "we asked it to ignore this", not "this can no longer appear". If you need a hard guarantee that something is never reported, that is a different mechanism and we would rather say so than let the wording imply more than it does.

And a suppression is always named. A finding that vanishes silently is indistinguishable from one nobody found, so the AI is required to state what it left out and which document said so. For the same reason it is told never to suppress something that looks like a NEW or CRITICAL failure, even when a document appears to cover it — an instruction written for a benign steady state must not hide an outage.

The Copilot's "Save to context" action (admin) distills a chat thread into a reusable context doc. One guardrail-enforced AI pass writes a compact summary, and only that summary is indexed for retrieval — the full verbatim transcript is preserved for audit in a collapsed block, but is deliberately excluded from search scoring so it never inflates results or snippets. The net effect is that a future question retrieves the distilled outcome instead of replaying the whole history. If no AI key is available, a deterministic extractive summary is saved instead, and the same AI Guardrails apply to the summarization pass.

From the Log Workspace, the "Include in AI" action attaches the open file to the Copilot dock as an explicit attachment — it goes to the AI dock, not the PTY terminal — and persists with that conversation, so you can hand the AI a log dump, a manifest, or captured output as first-class context without pasting it into the prompt.

Using the dock

Cmd-K or Ctrl-K opens the Copilot from anywhere. One session follows your tabs, so you can ask about whatever you're looking at without re-establishing context. Answers use bracketed node-id citations that you can click to deep-link to that resource's view, and inline Explain/Fix triggers appear on individual surfaces — a failing pod, a finding — to seed a scoped question.

Which writes stop for you

Every AI-proposed write pauses for your approval by default. That is the whole reason the agent is safe to point at a cluster, and it does not change.

But a long troubleshooting session is a lot of small, additive steps, and being asked to approve each one identically is how a safety control turns into a reflex — at which point nobody is really reading them. So Admin → AI Guardrails → Approve every write can be switched off, and then:

Runs on its own — creating a resource that does not exist, scaling up, creating an alert rule, starting a scan, putting a node back into service. Additive, and undoing them is a delete of the thing you just made.

Still stops for you — any delete, an apply over something already running, scaling to zero, a rolling restart, cordon or drain, any storage change, exec in a pod, writing a Secret, and anything KubeManta cannot classify. A tool added in a later release is gated until somebody classifies it deliberately, rather than inheriting permission by accident.

Note that apply_manifest lands on both sides: creating a resource is additive, replacing a live one can take an application down, so it is judged on what the cluster already contains rather than on the name of the tool. If we cannot tell — the API server is unreachable, the manifest does not parse — it stops for you.

Switching this off removes the CLICK, never the accounting. Auto-applied writes are audited, counted against the blast-radius window, subject to the circuit breaker and namespace scope, and shown in the conversation as they happen. There is deliberately no mode that turns approvals off entirely.

Setup

The Copilot reuses the existing chat loop, so it inherits every AI guardrail with zero new privileged surface: the master AI kill-switch, the data-residency allowlist, and cost caps all apply unchanged, and any write the AI proposes still flows through the approve-before-apply token gate: every write waits for a human approval by default, destructive writes wait unconditionally, and there is no mode that turns approvals off entirely. Whether or not a write stopped for a click, it is subject to a blast-radius check and a circuit-breaker check.

Free gets the structural graph plus a daily limit on Copilot chat (default 15 prompts per actor per day), which a licence lifts. When a Free actor exceeds it, the API returns a structured 402 that the dock renders as an Upgrade to Pro card rather than a raw error, and the count is tracked per actor per day.

A second, independent cap applies on every tier, licensed or not: cost_caps.viewer_ai_daily_limit in AI Guardrails limits how many AI calls a single viewer account may make in a day (default 50; 0 means unlimited). Admin accounts are not counted. A viewer over the cap gets the same 402. When Prompt Audit is enabled in AI Guardrails, Copilot chats — both the Anthropic and OpenAI paths — write the scrubbed prompt and response to the compliance log, since the Copilot is a first-class audited AI surface.

Troubleshooting

If the Copilot refuses to answer about a namespace you expect it to see, check the namespace allowlist/blocklist under AI Guardrails first — an out-of-scope target returns a structured error rather than raw data, by design. If chat stops responding partway through the day, that is a daily limit rather than a fault: on Free, the daily Copilot chat limit; for a viewer account on any tier, cost_caps.viewer_ai_daily_limit. Either surfaces in the dock as a card rather than a generic error, and both reset the next day. If citations don't deep-link correctly, confirm you're on a build that includes the Mobula-backed Copilot — the structural /graph/* endpoints are independent of the chat feature and can be used to sanity-check the underlying data directly.

Generated from KubeManta 1.2.0 — this page is rendered from the product's own documentation, so it cannot drift from what ships. Manifest built 2026-09-12T02:14:45Z.