fixpi — Remote OS Repair Agent

SSH into any Linux device, describe the problem, let the LLM diagnose and fix it.

fixpi -p "Docker won't start, cgroup error"           # one-liner
fixpi run -f /var/log/syslog -p "service crashing"    # attach log
fixpi run -d rpi3 -l groq -p "display not working"    # device + LLM profile
fixpi serve                                            # REST/WS API on :7771

Quick Start

cd fixPI
cp .env.example .env
# Set: RPI_HOST, RPI_USER, RPI_PASSWORD, LLM_MODEL, GROQ_API_KEY

pip install -e ".[clickmd]"
fixpi                        # interactive menu

# .env minimum:
RPI_HOST=raspberrypi.local
RPI_USER=tom
RPI_PASSWORD=secret
LLM_MODEL=groq/llama-3.3-70b-versatile
GROQ_API_KEY=gsk_...

CLI Reference

fixpi [OPTIONS] COMMAND [ARGS]

Global options:
  -p, --prompt TEXT   Problem to fix (runs immediately without menu)
  -f, --file PATH     Log/error file to attach as context

Commands:
  run          Diagnose & fix via LLM agent
  diagnose     Diagnose only — no changes applied
  serve        Start REST/WebSocket API server
  config       Configure LLM provider & SSH wizard
  test         Test LLM connection
  list-models  Show all supported LLM providers & models
  list-devices Show configured device profiles

run / diagnose options:
  -p, --prompt TEXT    Problem description
  -f, --file PATH      Log file to include as LLM context
  -d, --device NAME    Device profile (~/.fixpi/devices/NAME.env)
  -l, --llm NAME       LLM profile (~/.fixpi/llm/NAME.env)

serve options:
  --host TEXT          Bind host [default: 0.0.0.0]
  --port INT           Bind port [default: 7771]
  --reload             Dev mode

Examples

# Fix any problem:
fixpi -p "pydantic-core fails to install on Python 3.13"
fixpi run -p "Docker not starting" -f /var/log/syslog

# Diagnose without changes:
fixpi diagnose -p "why is systemd service crashing?"

# Multi-device:
fixpi run -d rpi3 -p "display black after reboot"
fixpi run -d rpi4-prod -l gemini -p "OOM killer active"

# Pipe log from stdin:
journalctl -u docker --since '1h ago' | fixpi run -f /dev/stdin

# REST API:
fixpi serve &
curl -X POST http://localhost:7771/run \
     -d '{"prompt": "fix display", "device": "rpi3"}' \
     -H 'Content-Type: application/json'

Device & LLM Profiles

# Create device profiles in ~/.fixpi/devices/NAME.env
mkdir -p ~/.fixpi/devices ~/.fixpi/llm

cat > ~/.fixpi/devices/rpi3.env << 'EOF'
RPI_HOST=192.168.1.100
RPI_USER=tom
RPI_PASSWORD=secret
EOF

cat > ~/.fixpi/llm/groq.env << 'EOF'
LLM_MODEL=groq/llama-3.3-70b-versatile
GROQ_API_KEY=gsk_...
EOF

# Use:
fixpi run -d rpi3 -l groq -p "fix problem"
fixpi list-devices

REST / WebSocket API

pip install 'fixpi[server]'   # fastapi + uvicorn
fixpi serve                   # http://localhost:7771

LLM Providers

Any litellm-compatible provider:

Note: groq/groq/llama-... is automatically normalized to groq/llama-...

What it fixes

Any Linux system problem accessible via SSH. Verified examples:

31 documented RPi examples: examples/

Verified: RPi3 + WaveShare 7.9" DSI (kernel 6.12.x)

# /boot/firmware/config.txt — working config
dtoverlay=vc4-kms-v3d
# display_auto_detect=1   ← must be disabled
dtoverlay=vc4-kms-dsi-waveshare-panel,7_9_inch
hdmi_force_hotplug=1

fixpi discovered this fix automatically by analysing kernel logs and dmesg.

Architecture

fixPI/
├── pyproject.toml
├── Makefile
├── .env.example
├── examples/             ← 31 documented RPi problems + integration guide
│   └── integration/      ← bash/Python/REST/WS/CI examples
├── tests/
│   ├── test_agent.py
│   ├── test_cli.py
│   ├── test_diagnostics.py
│   ├── test_llm_agent.py
│   └── e2e/              ← Docker-based SSH e2e tests
└── fixpi/
    ├── __main__.py       ← CLI entry point (clickmd)
    ├── cli.py            ← interactive menu + _load_profiles()
    ├── agent.py          ← LLM decision loop (generic + display mode)
    ├── server.py         ← FastAPI REST/WS server (fixpi serve)
    ├── llm_agent.py      ← multi-provider LLM via litellm
    ├── ssh_client.py     ← paramiko SSH + reboot/reconnect
    └── diagnostics.py    ← system state collector

Agent Modes

Integration

See examples/integration/README.md for:

• Bash pipe / one-liners
• Python SDK
• REST API via curl
• WebSocket streaming (Node.js + Python)
• c2004 installation fallback
• Multi-device management
• CI/CD pipeline example

License

Apache License 2.0 - see LICENSE for details.

Author

Created by Tom Sapletta - tom@sapletta.com