Posted on
• Artificial Intelligence

AI-Powered Linux Troubleshooting Chatbot

Author
  • User
    linuxbash
    Posts by this author
    Posts by this author

AI-Powered Linux Troubleshooting Chatbot: Fix Issues Faster From Your Terminal

It’s 2:13 a.m. A critical service is down. Logs are noisy, your brain is foggy, and time is burning. What if you could point an AI at the right system signals and get a clean, prioritized, actionable diagnosis—without leaving your shell?

This post shows you how to build and use a Bash-based, AI-powered troubleshooting chatbot that summarizes system state, reads recent errors, and helps you navigate to root cause. You can run it with a local model (for air‑gapped or sensitive environments) or a cloud API (for best accuracy).

Why this matters

  • Linux surfaces truth across dozens of sources: journalctl, dmesg, systemd, network sockets, disk usage, and more. Stitching that context together is the hard part.

  • AI is good at synthesis. With the right prompt and curated signals, it can explain symptoms, propose hypotheses, and list concrete next steps.

  • Keeping it in Bash means no new terminal UX, no heavyweight installs, and easy integration into scripts, CI, or incident runbooks.

What you’ll build

  • A single Bash script that:
    • Gathers a compact system snapshot (kernel, OS, disk/mem pressure, failing services, high‑priority logs).
    • Feeds this context plus your question to an AI backend.
    • Returns a concise, actionable diagnosis and next steps.

Backends supported:

  • Local: Ollama (run models like Llama 3 locally, no data leaves the box).

  • Cloud: Any OpenAI‑compatible API endpoint.

Prerequisites and installation

You’ll need curl and jq. Install them with your distro’s package manager:

  • Debian/Ubuntu (apt):

    sudo apt update
sudo apt install -y curl jq

  • Fedora/RHEL/CentOS (dnf):

    sudo dnf install -y curl jq

  • openSUSE/SLE (zypper):

    sudo zypper refresh
sudo zypper install -y curl jq

Optional (local AI): Install Ollama

  • One-line install:

    curl -fsSL https://ollama.com/install.sh | sh

  • Pull a local model (example):

    ollama pull llama3.1

Optional (cloud AI): Set environment for an OpenAI‑compatible API

  • Example with OpenAI: export OPENAI_API_KEY="sk-...your-key..." export OPENAI_MODEL="gpt-4o-mini" # or another available model # Optional: for non-OpenAI endpoints (OpenRouter, LocalAI, custom proxy): # export OPENAI_BASE_URL="https://your-endpoint.example.com/v1"

Create the chatbot script

Save this as ai-troubleshoot.sh and make it executable.

#!/usr/bin/env bash
# ai-troubleshoot.sh — AI-powered Linux troubleshooting chatbot
# Backends:
#   - Local: set BACKEND=ollama and MODEL (e.g., llama3.1)
#   - Cloud (OpenAI-compatible): set BACKEND=openai, OPENAI_API_KEY, OPENAI_MODEL, [OPENAI_BASE_URL]

set -euo pipefail

BACKEND="${BACKEND:-ollama}"               # ollama | openai
MODEL="${MODEL:-llama3.1}"                 # For ollama; e.g., llama3.1
OPENAI_MODEL="${OPENAI_MODEL:-gpt-4o-mini}"
OPENAI_BASE_URL="${OPENAI_BASE_URL:-https://api.openai.com/v1}"

if ! command -v curl >/dev/null 2>&1; then
  echo "error: curl is required" >&2; exit 1
fi
if ! command -v jq >/dev/null 2>&1; then
  echo "error: jq is required" >&2; exit 1
fi

question="${*:-}"
if [[ -z "$question" ]]; then
  echo "Usage: BACKEND=[ollama|openai] MODEL=<model> ./ai-troubleshoot.sh \"Why is nginx failing to start?\"" >&2
  exit 1
fi

collect_context() {
  local os kernel uptime_s mem disk failed journal dmesg_out net ps_top
  os=$( (cat /etc/os-release 2>/dev/null || true) )
  kernel=$(uname -r)
  uptime_s=$(uptime -p 2>/dev/null || true)
  mem=$(free -h 2>/dev/null || true)
  disk=$(df -hT --exclude-type=tmpfs --exclude-type=devtmpfs 2>/dev/null | head -n 20 || true)
  failed=$(systemctl --failed 2>/dev/null || true)
  journal=$(journalctl -p 3 -xb --no-pager -n 200 2>/dev/null || true)
  dmesg_out=$(dmesg --color=never --ctime --level=err,warn 2>/dev/null | tail -n 120 || true)
  net=$(ip -br a 2>/dev/null || true)
  ps_top=$(ps aux --sort=-%mem 2>/dev/null | head -n 12 || true)

  cat <<EOF
[System]
OS-Release:
$os

Kernel: $kernel
Uptime: $uptime_s

[Resources]
Memory (free -h):
$mem

Disk (top filesystems):
$disk

[Services]
Systemd failed units:
$failed

[Logs]
Journal (priority >= err, boot):
$journal

dmesg (err|warn, tail):
$dmesg_out

[Network]
ip -br a:
$net

[Processes]
Top memory consumers:
$ps_top
EOF
}

SYSTEM_PROMPT="You are a senior Linux SRE assistant. Read the provided system context and the user's question. 

- Identify the most probable root cause(s).

- Cite the key signals from the context that support your hypothesis.

- Provide 3–6 concrete next steps or commands to verify and fix.

- Be concise and specific. If data is missing, say what to collect next."

USER_PROMPT="$(collect_context)

[Question]
$question
"

run_ollama() {
  if ! command -v ollama >/dev/null 2>&1; then
    echo "error: ollama not found; install it or set BACKEND=openai" >&2
    exit 1
  fi
  printf "Thinking with %s (local)...\n\n" "$MODEL" >&2
  # For ollama, we pass a single composed prompt.
  printf "%s\n\n%s\n" "$SYSTEM_PROMPT" "$USER_PROMPT" | ollama run "$MODEL"
}

run_openai() {
  if [[ -z "${OPENAI_API_KEY:-}" ]]; then
    echo "error: OPENAI_API_KEY not set" >&2
    exit 1
  fi
  printf "Thinking with %s (cloud)...\n\n" "$OPENAI_MODEL" >&2
  local payload
  payload=$(jq -n \
    --arg model "$OPENAI_MODEL" \
    --arg sys "$SYSTEM_PROMPT" \
    --arg user "$USER_PROMPT" \
    '{model:$model, temperature:0.2, messages:[{role:"system",content:$sys},{role:"user",content:$user}]}' )
  curl -fsS -H "Content-Type: application/json" \
       -H "Authorization: Bearer ${OPENAI_API_KEY}" \
       -d "$payload" \
       "${OPENAI_BASE_URL}/chat/completions" \
    | jq -r '.choices[0].message.content'
}

case "$BACKEND" in
  ollama) run_ollama ;;
  openai) run_openai ;;
  *) echo "error: unknown BACKEND=$BACKEND (use ollama or openai)" >&2; exit 1 ;;
esac

Make it executable:

chmod +x ai-troubleshoot.sh

How to use it (real-world examples)

Example 1 — Service won’t start

sudo BACKEND=ollama MODEL=llama3.1 ./ai-troubleshoot.sh "nginx fails to start after config change. What's wrong?"

What you’ll get: a summary pointing to the failing unit in systemd, the exact error lines from journalctl, and commands like:

  • nginx -t to validate config

  • sudo journalctl -u nginx --no-pager -n 200

  • sudo ss -tulpn | grep :80 to check port conflicts

Example 2 — Disk pressure and package failures

sudo BACKEND=openai OPENAI_API_KEY="$OPENAI_API_KEY" OPENAI_MODEL="gpt-4o-mini" ./ai-troubleshoot.sh "apt upgrade keeps failing and system is sluggish."

Likely suggestions:

  • Show which filesystem is full (df -hT)

  • Clean APT cache (sudo apt clean) or remove old kernels

  • Check and repair dpkg locks

  • Journal entries that mention I/O or ENOSPC

Example 3 — Network outage or DNS weirdness

sudo BACKEND=ollama ./ai-troubleshoot.sh "Host can't resolve domains, but ping by IP works."

Likely suggestions:

  • Inspect resolv.conf and systemd-resolved status

  • Verify DNS servers and firewall rules

  • Check recent NetworkManager or netplan changes

Tip: Running with sudo surfaces more logs (journalctl, dmesg) when permissions restrict access.

Actionable playbook (3–5 quick wins)

  • Start local, escalate if needed

    • Use BACKEND=ollama for privacy and fast iteration.
    • Switch to BACKEND=openai for harder cases.

  • Tight loops, small prompts

    • Ask specific questions and re-run with narrowed focus (a specific unit, interface, or path).

  • Redact and scope

    • Avoid feeding secrets. Consider scrubbing tokens or IPs in the script if your environment requires it.

  • Save and share

    • Pipe output to files for incident timelines:
    sudo BACKEND=ollama ./ai-troubleshoot.sh "docker pulls timing out" | tee incident-2024-07-07.txt

  • Add to your toolbox

    • Wrap it in a function or alias, include in runbooks, or schedule a periodic health snapshot.

Notes on installation across distros

If you were missing jq or curl, install them as follows:

  • Debian/Ubuntu (apt):

    sudo apt update
sudo apt install -y curl jq

  • Fedora/RHEL/CentOS (dnf):

    sudo dnf install -y curl jq

  • openSUSE/SLE (zypper):

    sudo zypper refresh
sudo zypper install -y curl jq

For Ollama (local models), use:

curl -fsSL https://ollama.com/install.sh | sh

Then:

ollama pull llama3.1

Conclusion and next step

Modern Linux troubleshooting is about signal triage. With a small Bash script and an AI backend, you turn scattered logs and metrics into pointed, testable hypotheses—fast.

Your next step: 1) Install curl and jq using apt/dnf/zypper.
2) Optionally install Ollama and pull a local model.
3) Save the script as ai-troubleshoot.sh, make it executable, and ask it your first question.

When incidents hit, context and clarity shave minutes off your MTTR. Put this chatbot in your toolbox today.

Related posts