Kubani

AI-powered Kubernetes cluster automation and news monitoring platform with continuous learning capabilities.

Overview

Kubani is a multi-agent system for intelligent infrastructure management. It provisions and manages multi-node K3s clusters across heterogeneous hardware connected via Tailscale VPN, and provides AI-powered monitoring, remediation, and news aggregation.

Key Features:

Federated Agent Architecture: Specialized agents for different domains (K8s, News)
Voyager-Inspired Learning: Continuous improvement through Critic, Reflection, and Skill Synthesis
MCP Integration: Standardized tool access via Model Context Protocol servers
Unified Configuration: Single configuration system across all components
Discord Integration: Alerts, approvals, and feedback collection

Quick Start

# Install mise (runtime version manager)
curl https://mise.run | sh

# Clone and setup
git clone https://github.com/X-McKay/kubani.git
cd kubani
./setup.sh

# Install development tools
uv pip install -e .

# Initialize configuration
kubani init

# Run an agent locally
kubani local-run --agent k8s-monitor --hot-reload

Commands

All commands are managed via Just. Run just to see available commands.

just                  # List all commands
just setup            # Initial setup
just provision        # Provision cluster
just status           # Check cluster status
just tui              # Launch monitoring TUI

# Development
just test             # Run tests
just lint             # Lint code
just check            # Type check
just ci               # Pre-commit checks

# Agent builds
just build k8s-monitor    # Build agent image
just push k8s-monitor     # Push to registry

Project Structure

kubani/
├── kubani/                 # Core package
│   ├── framework/         # Core framework (config, events, memory, etc.)
│   ├── agents/            # Reusable agent implementations
│   ├── syndicates/        # Multi-agent orchestration systems
│   ├── mcp/               # MCP server infrastructure
│   ├── skills/            # Skill definitions (SKILL.md format)
│   └── evaluations/       # Evaluation suites
├── platform/              # Platform tooling
│   ├── cli/               # kubani development CLI
│   ├── registry/          # Metadata registry service
│   ├── skill-dev-tools/   # Skill development framework
│   └── ui/                # Web interface
├── infrastructure/        # Infrastructure as code
│   ├── gitops/            # Kubernetes manifests (Flux)
│   ├── ansible/           # Node provisioning playbooks
│   └── scripts/           # Utility scripts
├── config/                # Configuration files (hierarchical YAML)
├── docs/                  # Documentation
└── tests/                 # Integration tests

Agents

K8s Monitor

Intelligent Kubernetes cluster monitoring with automated remediation:

Pod failure investigation
Resource optimization
Anomaly detection
Pattern-based healing

News Monitor

AI-powered news aggregation and analysis:

Multi-source collection
Relevance filtering
Executive brief generation
Breaking news alerts

Skill Development

The Kubani skill development workflow is LLM-integrated and inspired by NVIDIA Voyager:

LLM-driven: Skills are natural language SOPs executed by LLMs
Self-improving: Critic agent and automatic retry enable continuous learning
High accuracy: Achieved 98.3% average accuracy on complex skills

# Create a new skill
kubani skill-llm draft "Find unused Kubernetes ConfigMaps"

# Evaluate it
kubani skill-llm eval skills/development/your-skill --verbose

# Improve it
kubani skill-llm improve skills/development/your-skill --goals accuracy

# Promote to production
kubani skill-llm promote skills/development/your-skill --category core

See the Skill Format Guide for skill structure and format details.

Agent Development

Local Development

# Run with cluster services
kubani local-run --agent k8s-monitor --temporal cluster --output console

# Run with hot-reload
kubani local-run --agent k8s-monitor --hot-reload

# Run with mock services (no cluster needed)
kubani local-run --agent k8s-monitor --mock-services

Configuration

Configuration is loaded hierarchically:

config.default.yaml - Base defaults
config.{environment}.yaml - Environment-specific
config.local.yaml - Local overrides (gitignored)
Environment variables with KUBANI_ prefix

Testing

# Run tests
kubani test k8s-monitor

# Run evaluations
kubani eval k8s-monitor

Deployment

# Deploy to cluster
kubani deploy --agent k8s-monitor --wait

MCP Servers

Kubani provides several MCP servers for agent tool access:

Server	Purpose
Temporal MCP	Workflow management
Qdrant MCP	Vector operations
Memory MCP	Unified memory interface
Discord MCP	Discord integration

Continuous Learning

The Voyager-inspired learning system includes:

Critic Agent: Evaluates execution quality
Reflection Agent: Synthesizes cross-agent knowledge
Skill Synthesizer: Generates new skills from patterns
Discord Approvals: Human-in-the-loop for skill proposals

Documentation

Comprehensive documentation organized by component: docs/

Getting Started:

Quickstart Guide - 5-minute setup
Installation - Detailed install guide

Development:

Local Development - Run agents locally
Creating Agents - Build new agents
Testing - Testing workflows
Contributing - How to contribute

Operations:

Production Checklist - Deploy to production
GitOps Deployment - Flux-based deployment
Operations Runbook - Syndicate operations

Configuration:

DNS & Traefik - DNS and ingress
GPU Setup - NVIDIA GPU configuration
Secrets Management - SOPS encryption
Authentication - Authentik SSO

Architecture:

System Overview - High-level architecture
Federated Agents - Multi-agent patterns
Learning System - Continuous learning
MCP Integration - MCP server design
ADRs - Architecture decisions

Reference:

CLI Commands - kubani reference
Error Codes - Error handling
Troubleshooting - Common issues

Prerequisites

Mise - Installs Python, kubectl, uv, just, earthly
Tailscale - Installed on all cluster nodes
SSH access to cluster nodes with sudo privileges

License

MIT

Name	sync-skills
Description	Sync Claude Code skills to other AI coding tools (Codex, Cursor, Gemini, GitHub Copilot, Kiro)

sync-skills

SKILL.md