KubeAgentiX CE

KubeAgentiX CE is an open-source Kubernetes diagnostics copilot focused on one core workflow:

Guided RCA -> Safe Action Plan -> Skill-driven execution

It helps operators and developers diagnose Kubernetes incidents faster using explainable evidence from cluster data (events, logs, status, metrics) while preserving execution safety with policy-guarded command routing.

1-Minute Setup

npx kubeagentix-ce@latest

KubeAgentiX CE starts on http://localhost:4000 by default.

If this project helps you, please star the repo: https://github.com/kubeagentix/kubeagentix-ce

Key Features

• Guided Quick Diagnosis (QuickDx) with confidence breakdown and evidence traces.
• AI-assisted Chat with deterministic fallback behavior.
• Terminal with dual modes:
  • Command mode (direct kubectl execution)
  • Natural Language mode (NL -> safe command suggestion -> edit -> execute)
• Skill-driven Runbooks for structured remediation workflows.
• Broker policy layer (allowlist, guardrails, typed errors, auditability).
• Browser-first architecture with optional WASM-assisted analysis helpers.

Why CLI Tools for Agentic Ops (vs MCP-heavy/custom stacks)

KubeAgentiX CE is deliberately built around real CLI tools for agents (starting with kubectl) instead of requiring every capability to be re-implemented as MCP/custom tools.

• Reuses existing kubeconfig, contexts, and plugin workflows operators already trust.
• Lowers integration overhead and maintenance burden for DevOps-heavy environments.
• Makes command preview + policy gating explicit before execution.
• Keeps behavior observable with concrete commands and outputs.

MCP/custom tools are still useful where needed, but CLI-first gives a faster and more pragmatic path for Kubernetes operations.

Architecture

flowchart LR
  UI["React UI\n(Chat, QuickDx, Runbooks, Terminal)"] --> API["Express API"]
  API --> BROKER["Command Broker\n(policy + adapters)"]
  BROKER --> KUBECTL["kubectl / cluster tools"]
  API --> RCA["RCA Service\n(heuristic + agentic enrichment)"]
  RCA --> LLM["LLM Providers\n(optional)"]
  UI --> WASM["WASM Helpers\n(client-side scoring)"]

Quickstart

Prerequisites

• Node.js 22+
• pnpm 10+
• kubectl installed and available on PATH
• kubeconfig/context configured (~/.kube/config or KUBECONFIG)

Option A: Docker Compose (Secondary)

git clone https://github.com/kubeagentix/kubeagentix-ce.git
cd kubeagentix-ce
cp .env.example .env
docker compose up --build

Docker mode mounts your host kubeconfig from ${HOME}/.kube and runs kubectl inside the container. For local clusters that expose the API server on 127.0.0.1/localhost (for example kind), the container starts localhost TCP bridges to the host by default so kubeconfig can keep using local endpoints.

Optional Bootstrap CLI (Secondary)

If you prefer scaffolding into a local folder first:

npx create-kubeagentix-ce@latest

Option B: Local From Source

git clone https://github.com/kubeagentix/kubeagentix-ce.git
cd kubeagentix-ce
pnpm install
cp .env.example .env
pnpm dev

Build and Test

pnpm typecheck
pnpm test
pnpm build
pnpm e2e
pnpm --dir docs-site build

Environment Variables

See .env.example for full set. Typical variables:

• PORT (default 4000)
• ANTHROPIC_API_KEY
• ANTHROPIC_AUTH_TOKEN (optional alternative to API key for Claude)
• OPENAI_API_KEY
• GOOGLE_API_KEY
• VITE_USE_WASM_CORE

If no LLM keys are set, heuristic fallback paths remain available for core diagnosis/suggestion flows.

Troubleshooting

• No kubectl found: For local mode, install kubectl and ensure it is on PATH. For Docker mode, rebuild the image: docker compose up --build.
• No kubeconfig found: Configure cluster access in ~/.kube/config or set KUBECONFIG.
• Docker + localhost cluster endpoint: If your kubeconfig uses localhost/127.0.0.1, keep KUBEAGENTIX_PROXY_LOCALHOST_KUBECONFIG=true (default) so the container can bridge localhost ports to the host endpoint.
• Port already in use: Run with a different port: PORT=4100 npx kubeagentix-ce@latest

Documentation

• User docs: docs-site/docs/users/
• Developer docs: docs-site/docs/developers/
• Docusaurus site: docs-site/

To run docs locally:

pnpm --dir docs-site install
pnpm --dir docs-site start

Security

• Security policy: SECURITY.md
• CI security checks include dependency review, vulnerability scan, secret scan, CodeQL, and SBOM generation.

Contributing

Contributions are welcome.

• Read CONTRIBUTING.md
• Follow CODE_OF_CONDUCT.md
• Open issues for bugs, UX gaps, and feature proposals

Roadmap (Public)

Near-term OSS focus:

• Improve RCA precision and explainability.
• Expand skills coverage and verification flows.
• Strengthen multi-cluster context handling.
• Improve observability integrations in a non-breaking way.
• Add an optional NPX bootstrap flow for one-command local startup.

Community

• GitHub: https://github.com/kubeagentix/kubeagentix-ce
• Discussions and issues are the primary feedback channel.
• Agentic DevOps Collective: https://agenticdevops.org/

If this project helps you, please star the repo: https://github.com/kubeagentix/kubeagentix-ce

Star History

License

Apache License 2.0. See LICENSE.