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.
npx kubeagentix-ce@latestKubeAgentiX CE starts on http://localhost:4000 by default.
If this project helps you, please star the repo: https://github.com/kubeagentix/kubeagentix-ce
- 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.
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.
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)"]
- Node.js 22+
- pnpm 10+
- kubectl installed and available on
PATH - kubeconfig/context configured (
~/.kube/configorKUBECONFIG)
git clone https://github.com/kubeagentix/kubeagentix-ce.git
cd kubeagentix-ce
cp .env.example .env
docker compose up --buildDocker 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.
It also mounts ${HOME}/.claude and includes Claude Code CLI so the
Claude Code (Subscription) provider can run without Anthropic API keys.
If you prefer scaffolding into a local folder first:
npx create-kubeagentix-ce@latestgit clone https://github.com/kubeagentix/kubeagentix-ce.git
cd kubeagentix-ce
pnpm install
cp .env.example .env
pnpm devpnpm typecheck
pnpm test
pnpm build
pnpm e2e
pnpm --dir docs-site buildSee .env.example for full set. Typical variables:
PORT(default4000)ANTHROPIC_API_KEYANTHROPIC_AUTH_TOKEN(legacy auth token alias; OAuth users should preferCLAUDE_CODE_OAUTH_TOKEN)OPENAI_API_KEYGOOGLE_API_KEYVITE_USE_WASM_COREENABLE_CLAUDE_SDK_BRIDGE(defaultfalse, enables websocket bridge for local Claude Code CLI)CLAUDE_SDK_CLI_PATH(defaultclaude)CLAUDE_SDK_LOCAL_HOST(default127.0.0.1)ENABLE_CLAUDE_CODE_PROVIDER(defaulttrue, auto-enables local Claude Code provider when CLI is available)CLAUDE_CODE_CLI_PATH(defaultclaude)CLAUDE_CODE_TIMEOUT_MS(default45000)CLAUDE_CODE_OAUTH_TOKEN(optional subscription/OAuth token for Claude Code provider, headless)CLAUDE_CODE_AUTH_TOKEN(legacy alias, still accepted)CLAUDE_CODE_SETTING_SOURCES(defaultproject,localto avoid user hook side-effects in non-interactive mode)
If no LLM keys are set, heuristic fallback paths remain available for core diagnosis/suggestion flows.
- 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/configor setKUBECONFIG. - Docker + localhost cluster endpoint:
If your kubeconfig uses
localhost/127.0.0.1, keepKUBEAGENTIX_PROXY_LOCALHOST_KUBECONFIG=true(default) so the container can bridge localhost ports to the host endpoint. - Claude SDK bridge disabled:
Set
ENABLE_CLAUDE_SDK_BRIDGE=true, then use:POST /api/claude-sdk/sessionsand connect browser websocket to/ws/browser/:sessionId. - Claude Code provider unavailable:
Install Claude Code CLI and keep
ENABLE_CLAUDE_CODE_PROVIDER=true. For local usage runclaude /login. For Docker/headless usage provideCLAUDE_CODE_OAUTH_TOKEN(subscription token) orANTHROPIC_API_KEY. You can also keep container env empty and paste token in Settings > Claude Code provider; the app now forwards this token per request (without requiring env injection). If auth still fails in Docker, setCLAUDE_CODE_OAUTH_TOKENexplicitly and recreate containers. You can also paste a Claude auth token in Settings > Claude Code provider (optional token field). - Port already in use:
Run with a different port:
PORT=4100 npx kubeagentix-ce@latest
- 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 policy: SECURITY.md
- CI security checks include dependency review, vulnerability scan, secret scan, CodeQL, and SBOM generation.
Contributions are welcome.
- Read CONTRIBUTING.md
- Follow CODE_OF_CONDUCT.md
- Open issues for bugs, UX gaps, and feature proposals
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.
- 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
Apache License 2.0. See LICENSE.