🔦 Lumo

Intelligent SRE/DevOps Automation Agent

AI-powered diagnostics + SSH automation + Kubernetes monitoring = Better SRE workflows

Features • Quick Start • Installation • Documentation • Contributing

📖 Overview

Lumo is a modern, intelligent automation agent that connects to your infrastructure, performs comprehensive diagnostics, and leverages AI to help you understand and fix issues faster. Think of it as your AI-powered SRE companion.

What Makes Lumo Different?

🤖 Multi-Provider AI Analysis - Claude, GPT-4, Gemini, Ollama, or OpenRouter
🔌 Zero-Config Localhost - Instant diagnostics without SSH overhead
☸️ Native Kubernetes - Direct API integration (no kubectl required)
🏗️ Agent Architecture - REST API + Agent daemon with hybrid push/pull model (Phases 7-8)
🔐 Security-First - Built-in security diagnostics and audit trails
🎯 Token-Optimized - TOON format reduces AI costs by 30-60%
🚀 Production-Ready - 66%+ test coverage, CI/CD, cross-platform

✨ Features

Core Capabilities

🔍 Comprehensive Diagnostics

6 Core Checks

CPU (load average, usage, cores)
Memory (usage, pressure, top consumers)
Disk (space, inodes, multi-filesystem)
Processes (count, zombies, resource hogs)
Services (systemd, init, launchd)
Network (interfaces, connectivity, latency)

4 Security Checks

Patch status (security updates)
Open ports (unexpected listeners)
SSH security (config audit)
Auth failures (brute force detection)

🤖 AI-Powered Analysis

5 Provider Support

Anthropic Claude (Sonnet 4.5)
OpenAI (GPT-4 Turbo, o1, o3)
Google Gemini (2.0 Flash)
Ollama (local models)
OpenRouter (multi-model routing)

Smart Features

Streaming responses
Token usage tracking
TOON format (30-60% cost savings)
Reasoning effort control (OpenAI)

Platform Support

Platform	SSH Diagnostics	Kubernetes	Proxmox VE
Linux	✅ Full support	✅ Native client	✅ Cluster monitoring
macOS	✅ Full support	✅ Native client	❌ N/A
BSD	✅ Full support	✅ Native client	❌ N/A
Windows	⏳ Planned	✅ Native client	❌ N/A

Kubernetes Diagnostics

Native cluster monitoring using k8s.io/client-go:

✅ 8 Resource Types - Nodes, Pods, Deployments, StatefulSets, DaemonSets, Services, PVCs, Events
✅ Read-Only - No modifications to your cluster
✅ Namespace Filtering - Check all or specific namespaces
✅ RBAC-Aware - Minimal permissions required (get/list)
✅ Context Switching - Work with multiple clusters

Reliability & Observability

🛡️ Circuit Breakers - Automatic failure protection for AI providers
🔍 Distributed Tracing - OpenTelemetry integration for request visibility
📊 Load Tested - Verified stability under high concurrency
🚦 Rate Limiting - Configurable per-IP and per-user limits

🚀 Quick Start

Prerequisites

Go 1.25+ (for building from source)
SSH access to target servers (or use localhost)
Optional: AI provider API key for analysis
Optional: kubeconfig for Kubernetes diagnostics

Installation

Option 1: Go Install (Recommended)

go install github.com/ignacio/lumo/cmd/lumo@latest

Option 2: Build from Source

git clone https://github.com/IgnacioPro/lumo.git
cd lumo
go build -o lumo ./cmd/lumo

# Optional: Install globally
sudo mv lumo /usr/local/bin/

Option 3: Download Binary (Coming Soon)

Pre-built binaries for Linux, macOS, and Windows will be available in Releases.

First Run

# 1. Diagnose your local machine (no configuration needed)
lumo diagnose localhost

# 2. Connect to a remote server
lumo connect user@server.com

# 3. Run remote diagnostics
lumo diagnose user@server.com

# 4. Add AI-powered analysis
export LUMO_ANTHROPIC_API_KEY=sk-ant-...
lumo diagnose localhost --analyze

Example Output

=== System Diagnostics for localhost ===

[✓] CPU Check (OK)
    Load Average: 1.23, 1.45, 1.67 (8 cores)
    Usage: 15.3%

[!] Memory Check (WARNING)
    RAM: 71.2% used (22.7/31.9 GB)
    Swap: 12.4% used (2.0/16.0 GB)
    Top Consumers:
      1. chrome (3.2 GB)
      2. docker (2.1 GB)
      3. postgres (1.8 GB)

[✓] Disk Check (OK)
    /: 45% used (225/500 GB)
    /home: 62% used (310/500 GB)

[✓] Network Check (OK)
    Interfaces: eth0 (UP), lo (UP)
    Connectivity: All targets reachable

Overall Status: WARNING (1 check needs attention)

🤖 AI Analysis:
Your system is healthy overall, but memory usage is approaching 75%.
Consider:
1. Closing unnecessary Chrome tabs (3.2 GB usage)
2. Reviewing Docker container memory limits
3. Tuning PostgreSQL shared_buffers if not needed

Estimated Impact: Moderate
Risk Level: Low

📚 Documentation

Command Reference

`diagnose` - Run System Diagnostics

# Localhost (no SSH)
lumo diagnose localhost

# Remote server
lumo diagnose user@server.com

# Specific checks only
lumo diagnose localhost --checks cpu,memory,disk

# With AI analysis
lumo diagnose localhost --analyze

# Different AI provider
lumo diagnose localhost --analyze --ai-provider openai

# JSON output
lumo diagnose localhost --format json

# TOON format (AI-optimized, 30-60% token reduction)
lumo diagnose localhost --format toon

# Kubernetes cluster
lumo diagnose --checks kubernetes

`connect` - Establish SSH Connection

# Auto-discover authentication
lumo connect user@server.com

# Specific key file
lumo connect user@server.com --key ~/.ssh/id_ed25519

# Custom port
lumo connect user@server.com --port 2222

# Skip test commands
lumo connect user@server.com --test=false

Configuration

Configuration File Locations (searched in order)

--config flag path
./config.yaml
~/.lumo/config.yaml

Quick Setup

# Copy example configuration
mkdir -p ~/.lumo
cp configs/config.example.yaml ~/.lumo/config.yaml

# Edit with your preferences
vim ~/.lumo/config.yaml

Environment Variables

# SSH Configuration
export LUMO_SSH_PORT=2222
export LUMO_SSH_STRICT_HOST_KEY_CHECKING=true

# AI Provider Selection
export LUMO_AI_PROVIDER=openai  # anthropic, openai, ollama, gemini, openrouter

# AI API Keys (Provider-Specific)
export LUMO_ANTHROPIC_API_KEY=sk-ant-...
export LUMO_OPENAI_API_KEY=sk-...
export LUMO_GEMINI_API_KEY=...
export LUMO_OPENROUTER_API_KEY=sk-or-...

# AI Settings
export LUMO_AI_TEMPERATURE=1.0
export LUMO_AI_MAX_TOKENS=4096
export LUMO_AI_REASONING_EFFORT=medium  # low, medium, high (OpenAI reasoning models)

# Logging
export LUMO_LOGGING_LEVEL=debug

# Kubernetes
export LUMO_DIAGNOSTICS_KUBERNETES_ENABLED=true
export LUMO_DIAGNOSTICS_KUBERNETES_CONTEXT=production

SSH Authentication Methods

Lumo tries authentication methods in this order:

SSH Agent (most secure) → Uses ssh-agent with loaded keys
Private Keys → Auto-discovers: id_ed25519, id_ecdsa, id_rsa, id_dsa
Password → Interactive prompt (secure, not stored)
Keyboard-Interactive → Supports 2FA/MFA

# Ensure SSH agent is running
eval $(ssh-agent)
ssh-add ~/.ssh/id_ed25519

# Verify keys loaded
ssh-add -l

Kubernetes Setup

# 1. Enable Kubernetes diagnostics
export LUMO_DIAGNOSTICS_KUBERNETES_ENABLED=true

# 2. (Optional) Use specific kubeconfig
export LUMO_DIAGNOSTICS_KUBERNETES_KUBECONFIG_PATH=/path/to/kubeconfig

# 3. (Optional) Use specific context
export LUMO_DIAGNOSTICS_KUBERNETES_CONTEXT=production

# 4. Run diagnostics
lumo diagnose --checks kubernetes

# 5. With AI analysis
lumo diagnose --checks kubernetes --analyze

RBAC Requirements

Lumo needs minimal read-only permissions:

apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
  name: lumo-reader
rules:
- apiGroups: [""]
  resources: ["nodes", "pods", "services", "persistentvolumeclaims", "events"]
  verbs: ["get", "list"]
- apiGroups: ["apps"]
  resources: ["deployments", "statefulsets", "daemonsets"]
  verbs: ["get", "list"]

🏗️ Architecture

┌─────────────────────────────────────────────────────────┐
│                    CLI Interface                        │
│         (connect, diagnose, fix, report, serve)         │
└────────────────────────┬────────────────────────────────┘
                         │
                    ┌────▼────┐
                    │ Config  │  YAML + Environment Variables
                    └────┬────┘
                         │
        ┌────────────────┼────────────────┐
        │                │                │
   ┌────▼────┐    ┌──────▼──────┐   ┌────▼────────┐
   │  Local  │    │     SSH     │   │ Kubernetes  │
   │Executor │    │  Executor   │   │   Client    │
   └────┬────┘    └──────┬──────┘   └──────┬──────┘
        │                │                 │
        └────────────────┼─────────────────┘
                         │
        ┌────────────────▼────────────────┐
        │    Diagnostics Runner (12)       │
        │  • 6 Core (CPU, Mem, Disk...)   │
        │  • 4 Security (Patches, Ports...)│
        │  • 2 Specialized (K8s, Proxmox) │
        └────────────────┬─────────────────┘
                         │
                    ┌────▼────┐
                    │Formatters│  Text, JSON, TOON
                    └────┬────┘
                         │
                    ┌────▼────────┐
                    │AI Analysis  │  5 Providers
                    │ (Optional)  │  Streaming
                    └─────────────┘

🧪 Testing

Overall Coverage: 66.7% (52 test files)

Coverage by Package

Package	Coverage	Status
`internal/diagnostics/formatters`	98.1%	✅ Excellent
`internal/diagnostics`	87.6%	✅ Excellent
`internal/config`	68.8%	✅ Good
`internal/diagnostics/checkers`	61.4%	✅ Good
`cmd/lumo`	61.6%	✅ Good
`internal/ssh`	30.5%	⚠️ In Progress
`internal/ai`	27.1%	⚠️ In Progress

Run Tests

# All tests
go test ./...

# With coverage
go test -cover ./...

# Specific package with verbose output
go test -v ./internal/diagnostics

# HTML coverage report
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

🗺️ Roadmap

✅ Completed Phases

🚧 In Progress

Phase 11: Messaging Integration (NATS, Kafka, RabbitMQ, Redis)

🔮 Future Phases

Phase 12: Security Hardening (mTLS, JWT, cert rotation, penetration testing)
Phase 13: Production Readiness (Performance, monitoring, dashboards, load testing)
Phase 14: Advanced Reporting (Markdown, HTML, PDF, trends, forecasting)
Phase 15: Advanced Features (Multi-cluster, ML-based anomaly detection)

🤝 Contributing

We welcome contributions! See our Contributing Guide for detailed instructions.

Quick Start

# Clone and setup
git clone https://github.com/IgnacioPro/lumo.git
cd lumo
make setup    # Install deps, start services, build

# Make changes
git checkout -b feature/my-feature
# ... edit code ...
make ci       # Run all checks before committing

# Submit PR
git push origin feature/my-feature

Ways to Contribute

🐛 Report bugs - Use the bug report template
💡 Suggest features - Use the feature request template
📖 Improve docs - Fix typos, add examples, clarify usage
🧪 Write tests - Help us improve coverage
🔧 Submit PRs - Fix bugs or implement features

Development Resources

CONTRIBUTING.md - Complete contributor guide
DEVELOPMENT.md - Build and test instructions
CODE_OF_CONDUCT.md - Community standards
SECURITY.md - Vulnerability reporting policy
SUPPORT.md - Support channels and guidelines
CLAUDE.md - Architecture reference

🔐 Security

Security Practices

✅ Host Key Verification - Enabled by default (StrictHostKeyChecking: true)
✅ No Password Flags - Passwords only via secure prompts
✅ API Keys - Environment variables only, never in config files
✅ Command Injection Prevention - Path sanitization and validation
✅ File Permissions - Validates SSH key permissions (600/400)

Reporting Security Issues

Please report security vulnerabilities privately according to SECURITY.md (GitHub Security Advisories).

📜 License

MIT License - See LICENSE file for details.

🙏 Acknowledgments

Built with these amazing technologies:

Cobra - CLI framework
Viper - Configuration management
Logrus - Structured logging
k8s.io/client-go - Kubernetes client
golang.org/x/crypto/ssh - SSH implementation

AI Providers:

Anthropic Claude - Leading AI safety and research
OpenAI - GPT-4 and advanced reasoning models
Google Gemini - Multimodal AI
Ollama - Run LLMs locally
OpenRouter - Multi-provider AI routing

📞 Support

📖 Documentation: CLAUDE.md | DEVELOPMENT.md
🐛 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
🛟 Support Policy: SUPPORT.md
⭐ Star us on GitHub if you find Lumo useful!

⬆ Back to Top

Made with ❤️ by the Lumo community

Name		Name	Last commit message	Last commit date
Latest commit History 523 Commits
.github		.github
REPORTS		REPORTS
api		api
cmd		cmd
configs		configs
demos		demos
deployments		deployments
docs		docs
examples		examples
internal		internal
scripts		scripts
tests		tests
website		website
.dockerignore		.dockerignore
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.golangci.yml		.golangci.yml
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DEVELOPMENT.md		DEVELOPMENT.md
Dockerfile		Dockerfile
Dockerfile.agent		Dockerfile.agent
EVENT_DRIVEN_IMPLEMENTATION.md		EVENT_DRIVEN_IMPLEMENTATION.md
LICENSE		LICENSE
Makefile		Makefile
PHASE_11C_SUMMARY.md		PHASE_11C_SUMMARY.md
README.md		README.md
ROADMAP_TODO.md		ROADMAP_TODO.md
ROADMAP_TO_VISION.md		ROADMAP_TO_VISION.md
SECURITY.md		SECURITY.md
SUPPORT.md		SUPPORT.md
TESTING_ENVIRONMENT.md		TESTING_ENVIRONMENT.md
docker-compose.yaml		docker-compose.yaml
go.mod		go.mod
go.sum		go.sum

Folders and files

Latest commit

History

Repository files navigation

🔦 Lumo

📖 Overview

What Makes Lumo Different?

✨ Features

Core Capabilities

🔍 Comprehensive Diagnostics

🤖 AI-Powered Analysis

Platform Support

Kubernetes Diagnostics

Reliability & Observability

🚀 Quick Start

Prerequisites

Installation

Option 1: Go Install (Recommended)

Option 2: Build from Source

Option 3: Download Binary (Coming Soon)

First Run

Example Output

📚 Documentation

Command Reference

diagnose - Run System Diagnostics

connect - Establish SSH Connection

Configuration

Configuration File Locations (searched in order)

Quick Setup

Environment Variables

SSH Authentication Methods

Kubernetes Setup

RBAC Requirements

🏗️ Architecture

🧪 Testing

Coverage by Package

Run Tests

🗺️ Roadmap

✅ Completed Phases

🚧 In Progress

🔮 Future Phases

🤝 Contributing

Quick Start

Ways to Contribute

Development Resources

🔐 Security

Security Practices

Reporting Security Issues

📜 License

🙏 Acknowledgments

📞 Support

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 9

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`diagnose` - Run System Diagnostics

`connect` - Establish SSH Connection

Packages