Skip to content

Architecture

KubeManta runs entirely inside your own Kubernetes cluster: the agent (with a lower-privilege 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 · Claude Code<br/>(lower-privilege, no secrets)"]
    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 a lower-privilege 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. Only a license heartbeat (cluster fingerprint + license key) reaches the KubeManta license service.

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 512 Mi mem request == limit, 250m CPU request, no CPU limit
kubemanta-ui The dashboard 250m CPU / 256 Mi limit
Terminal sidecar Browser PTY, runs inside the agent pod as a lower-privilege user 1 CPU / 4 Gi limit
kubemanta-expert-exec Separate, isolated pod holding the cluster-admin token (only when expertMode.enabled=true) 500m 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, no secrets, a distinct lower-privilege user in its own process namespace.

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 off by default (rbac.readSecrets=false).

LLM providers

Supported providers (configured per-session via AI Settings):

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); gated behind a Pro license.