NannyAgent - Linux Diagnostic Agent

A Go-based AI agent that diagnoses Linux system issues using eBPF-powered deep monitoring and TensorZero AI integration.

Features

• 🤖 AI-Powered Diagnostics - Intelligent issue analysis and resolution planning
• 🔍 eBPF Deep Monitoring - Real-time kernel-level tracing for network, processes, files, and security events
• 🛡️ Safe Command Execution - Validates and executes diagnostic commands with timeouts
• 📊 Automatic System Information Gathering - Comprehensive OS, kernel, CPU, memory, and network metrics
• 🔄 WebSocket Integration - Real-time communication with backend investigation system
• 🔐 OAuth Device Flow Authentication - Secure agent registration and authentication
• ✅ Comprehensive Integration Tests - Realistic Linux problem scenarios

Requirements

• Operating System: Linux only (no containers/LXC support)
• Architecture: amd64 (x86_64) or arm64 (aarch64)
• Kernel Version: Linux kernel 5.x or higher
• Privileges: Root/sudo access required for eBPF functionality
• Dependencies: bpftrace and bpfcc-tools (automatically installed by installer)
• Network: Connectivity to Supabase backend

Quick Installation

One-Line Install (Recommended)

# Download and run the installer
curl -fsSL https://your-domain.com/install.sh | sudo bash

Or download first, then install:

# Download the installer
wget https://your-domain.com/install.sh

# Make it executable
chmod +x install.sh

# Run the installer
sudo ./install.sh

Manual Installation

1. Clone this repository:

   git clone https://github.com/yourusername/nannyagent.git
   cd nannyagent
   

2. Run the installer script:

   sudo ./install.sh
   

The installer will:

• ✅ Verify system requirements (OS, architecture, kernel version)
• ✅ Check for existing installations
• ✅ Install eBPF tools (bpftrace, bpfcc-tools)
• ✅ Build the nannyagent binary
• ✅ Test connectivity to Supabase
• ✅ Install to /usr/local/bin/nannyagent
• ✅ Create configuration in /etc/nannyagent/config.env
• ✅ Create secure data directory /var/lib/nannyagent

Configuration

After installation, configure your Supabase URL:

# Edit the configuration file
sudo nano /etc/nannyagent/config.env

Required configuration:

# Supabase Configuration
SUPABASE_PROJECT_URL=https://your-project.supabase.co

# Optional Configuration
TOKEN_PATH=/var/lib/nannyagent/token.json
DEBUG=false

Command-Line Options

# Show version (no sudo required)
nannyagent --version
nannyagent -v

# Show help (no sudo required)
nannyagent --help
nannyagent -h

# Run the agent (requires sudo)
sudo nannyagent

Usage

1. First-time Setup - Authenticate the agent:

   sudo nannyagent
   

   The agent will display a verification URL and code. Visit the URL and enter the code to authorize the agent.

2. Interactive Diagnostics - After authentication, enter system issues:

   > On /var filesystem I cannot create any file but df -h shows 30% free space available.
   

3. The agent will:

   • Gather comprehensive system information automatically
   • Send the issue to AI for analysis via TensorZero
   • Execute diagnostic commands safely
   • Run eBPF traces for deep kernel-level monitoring
   • Provide AI-generated root cause analysis and resolution plan

4. Exit the agent:

   > quit
   

   or

   > exit
   

How It Works

1. User Input: Submit a description of the system issue you're experiencing
2. System Info Gathering: Agent automatically collects comprehensive system information and eBPF capabilities
3. AI Analysis: Sends the issue description + system info to NannyAPI for analysis
4. Diagnostic Phase: AI returns structured commands and eBPF monitoring requests for investigation
5. Command Execution: Agent safely executes diagnostic commands and runs eBPF traces in parallel
6. eBPF Monitoring: Real-time system tracing (network, processes, files, syscalls) provides deep insights
7. Iterative Analysis: Command results and eBPF trace data are sent back to AI for further analysis
8. Resolution: AI provides root cause analysis and step-by-step resolution plan based on comprehensive data

Testing & Integration Tests

The agent includes comprehensive integration tests that simulate realistic Linux problems:

Available Test Scenarios:

1. Disk Space Issues - Inode exhaustion scenarios
2. Memory Problems - OOM killer and memory pressure
3. Network Issues - DNS resolution problems
4. Performance Issues - High load averages and I/O bottlenecks
5. Web Server Problems - Permission and configuration issues
6. Hardware/Boot Issues - Kernel module and device problems
7. Database Performance - Slow queries and I/O contention
8. Service Failures - Startup and configuration problems

Run Integration Tests:

# Run unit tests
make test

# Run integration tests
./tests/test_ebpf_integration.sh

Installation Exit Codes

The installer uses specific exit codes for different failure scenarios:

Exit Code	Description
0	Success
1	Not running as root
2	Unsupported operating system (non-Linux)
3	Unsupported architecture (not amd64/arm64)
4	Container/LXC environment detected
5	Kernel version < 5.x
6	Existing installation detected
7	eBPF tools installation failed
8	Go not installed
9	Binary build failed
10	Directory creation failed
11	Binary installation failed

Troubleshooting

Installation Issues

Error: "Kernel version X.X is not supported"

• NannyAgent requires Linux kernel 5.x or higher
• Upgrade your kernel or use a different system

Error: "Another instance may already be installed"

• Check if /var/lib/nannyagent exists
• Remove it if you're sure: sudo rm -rf /var/lib/nannyagent
• Then retry installation

Warning: "Cannot connect to Supabase"

• Check your network connectivity
• Verify firewall settings allow HTTPS connections
• Ensure SUPABASE_PROJECT_URL is correctly configured in /etc/nannyagent/config.env

Runtime Issues

Error: "This program must be run as root"

• eBPF requires root privileges
• Always run with: sudo nannyagent

Error: "Cannot determine kernel version"

• Ensure uname command is available
• Check system integrity

Development

Building from Source

# Clone repository
git clone https://github.com/yourusername/nannyagent.git
cd nannyagent

# Install Go dependencies
go mod tidy

# Build binary
make build

# Run locally (requires sudo)
sudo ./nannyagent

Running Tests

# Run unit tests
make test

# Test eBPF capabilities
./tests/test_ebpf_integration.sh

Safety

eBPF Monitoring Capabilities

The agent includes advanced eBPF (Extended Berkeley Packet Filter) monitoring for deep system investigation:

• System Call Tracing: Monitor process behavior through syscall analysis
• Network Activity: Track network connections, data flow, and protocol usage
• Process Monitoring: Real-time process creation, execution, and lifecycle tracking
• File System Events: Monitor file access, creation, deletion, and permission changes
• Performance Analysis: CPU, memory, and I/O performance profiling
• Security Events: Detect privilege escalation and suspicious activities

The AI automatically requests appropriate eBPF monitoring based on the issue type, providing unprecedented visibility into system behavior during problem diagnosis.

For detailed eBPF documentation, see EBPF_README.md.

Safety

• All commands are validated before execution to prevent dangerous operations
• Read-only diagnostic commands are prioritized
• No commands that modify system state (rm, mv, etc.) are executed
• Commands have timeouts to prevent hanging
• Secure execution environment with proper error handling
• eBPF monitoring is read-only and time-limited for safety

API Integration

The agent uses the github.com/sashabaranov/go-openai SDK to communicate with NannyAPI's OpenAI-compatible API endpoint. This provides:

• Robust HTTP client with retries and timeouts
• Structured request/response handling
• Automatic JSON marshaling/unmarshaling
• Error handling and validation

Example Session

Linux Diagnostic Agent Started
Enter a system issue description (or 'quit' to exit):
> Cannot create files in /var but df shows space available

Diagnosing issue: Cannot create files in /var but df shows space available
Gathering system information...

AI Response:
{
  "response_type": "diagnostic",
  "reasoning": "The 'No space left on device' error despite available disk space suggests inode exhaustion...",
  "commands": [
    {"id": "check_inodes", "command": "df -i /var", "description": "Check inode usage..."}
  ]
}

Executing command 'check_inodes': df -i /var
Output:
Filesystem      Inodes   IUsed   IFree IUse% Mounted on
/dev/sda1      1000000  999999       1  100% /var

=== DIAGNOSIS COMPLETE ===
Root Cause: The /var filesystem has exhausted all available inodes
Resolution Plan: 1. Find and remove unnecessary files...
Confidence: High

Note: The AI receives comprehensive system information including:

• Hostname, OS version, kernel version
• CPU cores, memory, system uptime
• Network interfaces and private IPs
• Current load average and disk usage

Available Make Commands

• make build - Build the application
• make run - Build and run the application
• make clean - Clean build artifacts
• make test - Run unit tests
• make install - Install dependencies
• make build-prod - Build for production
• make install-system - Install system-wide (requires sudo)
• make fmt - Format code
• make help - Show available commands

Testing Commands

• ./test-examples.sh - Show interactive test scenarios
• ./integration-tests.sh - Run automated integration tests
• ./discover-functions.sh - Find available NannyAPI functions
• ./install.sh - Installation script for Linux VMs