Local LLM Linux Troubleshoot: An AI Agent for Linux Diagnostics

Introduction

Local LLM Linux Troubleshoot is an innovative local AI agent crafted to simplify Linux system diagnostics and troubleshooting. It integrates with llama.cpp to provide an intelligent assistant that can scan your host, interpret logs, explain potential issues, and propose solutions. The project emphasizes safety, requiring explicit permission before executing any system-altering commands, and supports both command-line and a user-friendly web interface.

Why Use and Benefits

This project offers a powerful set of features for anyone managing Linux systems, from homelab enthusiasts to sysadmins:

• Comprehensive Diagnostics: Performs read-only diagnostics across services, packages, boot processes, storage, network, display, audio, and Bluetooth.
• Intelligent Explanations: Streams model output in chat, including collapsible reasoning to help users understand the AI's thought process.
• Privacy-First: Operates locally with llama.cpp models, ensuring your system data remains on your machine.
• Safe Command Execution: Utilizes a safety controller that requires explicit user permission in the GUI before executing any modifying commands, logging all approved actions to a local audit trail.
• Configurable: Allows users to customize model, context, token settings, permissions, and theme directly from the web GUI.
• Persistent Data: Maintains chat history in the browser and local scan memory in a dedicated .lta_data/ directory.
• Versatile Access: Offers both a command-line interface (CLI) for quick queries and a web GUI for a more interactive experience.
• Docker Support: Easy deployment as a local, restart-always Docker service, simplifying setup and management.

Installation

Docker Setup

To run the application as a local, restart-always Docker service, use the following commands:

docker compose up -d --build

Once started, open your browser to:

http://127.0.0.1:28765/

For added security, you can set a local UI password:

export LTA_UI_PASSWORD='choose-a-local-password'
docker compose up -d --build

Run Without Docker

If you prefer to run the application directly, ensure you have Python 3.10+ installed and then execute:

PYTHONPATH=src python3 -m linux_troubleshoot_agent.web

You can also set useful defaults via environment variables:

export LLAMA_CPP_BASE_URL=http://127.0.0.1:11435/v1
export LLAMA_CPP_MODEL=local-model
export LTA_MAX_TOKENS=4096
export LTA_TEMPERATURE=0.2
export LTA_TOP_P=0.95
export LTA_TOP_K=40
export LTA_REPEAT_PENALTY=1.1

Examples

CLI Usage

Ask a troubleshooting question directly from the command line:

PYTHONPATH=src python3 -m linux_troubleshoot_agent "HDMI monitor is not detected"

Check the safety classification of a command:

PYTHONPATH=src python3 -m linux_troubleshoot_agent --check-command "journalctl -p 3 -xb"

Links

For more details, source code, and to contribute, visit the official GitHub repository:

• GitHub Repository