Skip to content

Architecture

KubeManta runs entirely inside your own Kubernetes cluster: the agent (with its browser-terminal sidecar) and the dashboard, plus a separate, isolated cluster-admin pod only when Expert Mode is enabled. It is read-only by default, uses your own LLM key, and your cluster data never leaves your infrastructure.

How it works

flowchart TB
  team["Your team<br/>(browser)"]

  subgraph cluster["Your Kubernetes cluster"]
    direction TB
    ui["KubeManta Dashboard<br/>(UI pod)"]
    subgraph agentpod["Agent pod"]
      agent["KubeManta Agent<br/>observability · AI diagnosis · SRE automation"]
      term["Terminal sidecar<br/>PTY · kubectl/k9s/helm<br/>(admins only, own ServiceAccount)"]
    end
    expert["Expert-exec pod<br/>cluster-admin token<br/>(only with Expert Mode)"]
    workloads["Your workloads<br/>& cluster API"]
    ui --> agent
    agent -.->|"bearer-auth HTTP<br/>(NetworkPolicy-restricted)"| expert
    agent -->|read-only by default<br/>writes are opt-in| workloads
    expert -->|privileged ops<br/>ephemeral kubeconfig| workloads
  end

  team --> ui
  agent -->|"Bring your own LLM<br/>(your API key, or local Ollama<br/>for full data residency)"| llm["Claude / your LLM"]
  agent -.->|verifies your license| lic["KubeManta<br/>License Service"]

  subgraph onboard["Getting started"]
    direction TB
    site["kubemanta.com<br/>sign up — Free or Pro"]
    key["Your license key"]
    images["KubeManta<br/>Container Registry"]
    site --> key
    key -->|"helm install --set license.key=…"| cluster
    key -.->|authenticates image pulls| images
    images --> cluster
  end

Key design points

In-cluster only. KubeManta deploys as three pods: the agent (with its browser-terminal sidecar container), the dashboard, and — only when Expert Mode is enabled — a separate, isolated pod that alone holds the cluster-admin token. Nothing about your workloads is sent to KubeManta — K8s API calls are made in-cluster via a ServiceAccount.

Read-only by default. KubeManta observes and diagnoses; any write or remediation action is opt-in and requires either a Helm flag (rbac.allowWrites=true) or explicit user approval in the UI.

Bring your own LLM. Use your own Claude, OpenAI, Gemini, or Groq key. For full data residency (no cluster data leaving your network), point it at a local Ollama instance.

License-as-pull. Your license key is the registry password for registry.kubemanta.com. One --set license.key=YOUR_KEY flag is all that's needed — the chart builds the pull secret automatically.

Your data stays yours. AI analysis runs in your cluster using your key. No prompts, logs, or cluster data are retained by KubeManta. The licence service receives licence validation and a heartbeat (your licence key and a cluster fingerprint) and, by default, the cluster's node count — a number only. Everything else that leaves the cluster is something you configure; see Network Egress.

Request routing

Browser
  └─► https://your-hostname (Ingress / GCE · ALB · Traefik)
            │
            ├── /api/agent/terminal/ws/* ──────► kubemanta-agent:8080 (WebSocket, direct)
            │
            └── /* ────────────────────────────► kubemanta-ui:3000 (the dashboard)
                          │
                          │  /api/agent/* → proxied over in-cluster DNS
                          │
                          └─► kubemanta-agent:8080 (the agent, HTTP)

WebSocket connections (PTY terminal) are routed directly from the Ingress to the agent — they are not proxied through the dashboard, which does not handle the HTTP→WebSocket upgrade.

Components

Component Role Default resources
kubemanta-agent The agent — observability, AI diagnosis, SRE automation 250m CPU / 1 Gi request; 2 CPU / 2 Gi limit
kubemanta-ui The dashboard 1 CPU / 256 Mi limit
Terminal sidecar Browser PTY for admins, inside the agent pod as a separate unprivileged OS user; kubectl there uses its own ServiceAccount, <release>-terminal 2 CPU / 8 Gi limit
kubemanta-expert-exec Separate, isolated pod holding the cluster-admin token (only when expertMode.enabled=true) 1 CPU / 256 Mi limit
Embedded database PVC-backed, in-cluster only 1 Gi PVC (configurable)

Three security contexts

Privilege is split so no single process holds everything:

  • Agent — the database, encryption key, session secrets, SSO config; a read-only reader ServiceAccount by default.
  • Expert-exec pod — the only place the cluster-admin token lives (when Expert Mode is on). The agent delegates privileged ops to it over a bearer-authenticated, NetworkPolicy-restricted hop; it builds an ephemeral kubeconfig that is discarded after every operation.
  • Terminal sidecar — its own storage and a distinct unprivileged OS user in its own container; the database and encryption key file are not mounted into it. Its kubectl runs as a separate Kubernetes identity, the <release>-terminal ServiceAccount, whose short-lived token the agent mints: the agent's read permissions (and its writes, with rbac.allowWrites, though never in KubeManta's own namespace), but never the Secrets in KubeManta's own namespace, and elsewhere only Secrets in namespaces listed in terminal.secretsNamespaces. terminal.clusterCredentials.enabled=false withholds the credential altogether.

See Security Model.

Mobula

Mobula is KubeManta's live model of the cluster — what exists, how it is connected, and what is currently wrong. It is assembled on demand from the agent's existing collectors and operational memory, so there is no graph store to run or back up. It grounds the AI Copilot (answers cite the resources they came from) and is exposed structurally at GET /graph/subgraph / GET /graph/entity/{id} (Free, deterministic topology). The Mobula view in the dashboard is the visual UI over that same surface.

K8s API access

The agent talks to the Kubernetes API with a single pooled, reused connection for efficiency.

API group Resources
core/v1 pods, pods/log, services, endpoints, configmaps, secrets*, events, PVCs, nodes, namespaces
apps/v1 deployments, statefulsets, daemonsets, replicasets
networking/v1 ingresses, networkpolicies
batch/v1 jobs, cronjobs

* Secrets read is on by default (rbac.readSecrets=true); Secret delete is never granted.

LLM providers

Supported providers (configured by an admin in AI Settings; the key is stored encrypted in-cluster):

Provider Notes
Anthropic Claude models
OpenAI GPT-4, o-series
Google Gemini Gemini Pro / Flash
Azure OpenAI Enterprise Azure endpoint
Groq Fast inference
Ollama Local / self-hosted — full data residency
Custom Any OpenAI-compatible endpoint

MCP server

GET /mcp/tools and POST /mcp/tools/call expose KubeManta's read-only K8s tools in Model Context Protocol format for external AI agents (Claude Desktop, Cursor, custom agents). Authenticated with a per-user API key (X-API-Key); available on every tier, and read-only on all of them. See the MCP server guide, and the API reference for the same key used against the ordinary REST surface.