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	testing
Description	Testing patterns, fixtures, and best practices for Kubani. Use this skill when writing or running tests.

testing

SKILL.md