ArchGuard AI

Native desktop AI system assistant for Arch Linux. Monitors CPU, memory, disk, network, processes, and systemd services; analyzes logs with a local Ollama LLM; and executes maintenance actions only after safety validation and explicit user approval.

Requirements

• Python 3.12
• PySide6 (Qt)
• Ollama (local LLM)
• SQLite (stdlib)
• psutil
• systemd + journalctl (Arch Linux target)

Quick Start — Ubuntu WSL (development)

Fast path (no sudo, no apt update) — if Python 3.12 is already installed:

chmod +x scripts/*.sh
./scripts/install_python_only.sh
source .venv/bin/activate
python scripts/test_snapshot.py

Full path — installs Qt runtime libs via apt (skips apt update):

./scripts/install_ubuntu_wsl.sh

GUI in WSL requires a display server (WSLg or X11). On Arch, run natively on the desktop session.

Quick Start — Arch Linux

cd /path/to/dproj          # project root, not scripts/
chmod +x scripts/*.sh
./scripts/install_arch.sh
./scripts/setup_ollama.sh llama3.2
python -m archguard

Arch package names (used by install_arch.sh):

Wrong	Correct
python-pyside6	pyside6
psutil	python-psutil

If pacman says target not found, sync once then retry:

sudo pacman -Sy
./scripts/install_arch.sh

If pip: command not found, install pip first:

sudo pacman -S python-pip
./scripts/install_python_only.sh

VMware shared folder (/mnt/hgfs/)

HGFS does not support symlinks, so python -m venv fails with Operation not supported. The install scripts detect this automatically and place the venv at:

~/.local/venvs/archguard-dproj

Run from project root:

rm -rf .venv venv          # remove any broken partial venvs
sh scripts/fix_scripts.sh  # fix CRLF if you see "set: pipefail" errors
./scripts/install_arch.sh
./scripts/run_dev.sh       # launches app using the correct venv

If scripts fail with set: pipefail or invalid option name, they have Windows line endings. Fix once with:

sh scripts/fix_scripts.sh
# or: sed -i 's/\r$//' scripts/*.sh

Or:

python -m archguard

Project Layout

src/archguard/
  core/           # Domain: collectors, AI, safety, executor, memory, use cases
  infrastructure/ # SQLite, Ollama, psutil, systemd, journalctl
  gui/            # PySide6 desktop interface
  utils/          # Logging, formatters, environment checks
config/           # settings.toml, safety_rules.toml
assets/styles/    # Qt dark theme
data/             # SQLite DB and logs (runtime)
scripts/          # Install and dev helpers
tests/            # Unit tests

Safety Model

1. AI proposes actions as structured ActionRequest objects — never raw shell.
2. CommandValidator blocks dangerous patterns and non-allowlisted services.
3. GUI shows ApprovalDialog before every execution.
4. All attempts are logged to action_history in SQLite.

Edit config/safety_rules.toml to adjust allowed services and blocked patterns.

Configuration

File	Purpose
config/settings.toml	Poll interval, Ollama model, DB path, GUI size
config/safety_rules.toml	Blocked commands, allowed service restarts
.env	Optional overrides (OLLAMA_HOST, OLLAMA_MODEL)

Testing

source .venv/bin/activate
pytest
python scripts/test_snapshot.py

Migration WSL → Arch

1. Copy the project directory to Arch.
2. Run ./scripts/install_arch.sh.
3. Run ./scripts/setup_ollama.sh.
4. Launch with python -m archguard from a graphical session.
5. Service restart/kill actions may require appropriate polkit/sudo permissions.

University Report Notes

• Clean architecture: GUI → use cases → domain → infrastructure adapters
• Safety layer: Validator + approval dialog + audit log
• Local AI: Ollama HTTP API, no cloud dependency
• Persistence: Issues, solutions, recommendations, analysis sessions