Loki — Agent IA local sur Ollama

Loki est un atelier d'agent IA 100 % local, conçu pour se connecter à Ollama et travailler en mode agentique : un tchat, des outils (lecture/écriture de fichiers, aperçu HTML en direct…) et un workspace de fichiers. Pensé pour un déploiement Docker simple.

Le thème visuel (« atelier café », sombre et chaleureux, accent ambre) est décliné fidèlement depuis la maquette d'origine.

Architecture

Frontend (React + Vite + TS + Tailwind)
        │ HTTP + SSE
Backend (FastAPI, Python)
   ├── /api/status, /api/models, /api/models/pull   (Ollama)
   ├── /api/sessions  (CRUD sessions)
   ├── /api/chat      (boucle agentique + outils, streaming SSE)
   ├── /api/files     (arborescence + contenu du workspace)
   │   Outils agent : read_file · write_file · list_dir (confinés au workspace)
        │ httpx                     │ volume
     Ollama (:11434)            /workspace + /data (SQLite)

Un seul conteneur : le backend FastAPI sert l'API et le frontend compilé. Loki se connecte à un Ollama existant via OLLAMA_HOST.

Démarrage rapide (Docker)

cp .env.example .env          # ajuste OLLAMA_HOST si besoin
docker compose up --build

Application disponible sur http://localhost:8717

Ollama : par défaut Loki vise http://host.docker.internal:11434 (un Ollama installé sur la machine hôte). Pour embarquer Ollama dans la stack : docker compose --profile ollama up puis règle OLLAMA_HOST=http://ollama:11434.

Installation sur Unraid

L'image est construite et publiée automatiquement par GitHub Actions sur GHCR (ghcr.io/r0m1k3/loki:latest) à chaque push sur main. Aucun build ni git n'est nécessaire sur Unraid — un simple pull. Compose prêt à l'emploi : docker-compose.unraid.yml.

1. Dans le terminal Unraid, crée les dossiers de données :

   mkdir -p /mnt/user/appdata/loki/workspace /mnt/user/appdata/loki/data
   

2. Installe le plugin Compose Manager (Apps), crée une nouvelle stack, et colle le contenu de docker-compose.unraid.yml.
3. Adapte OLLAMA_HOST : mets l'IP de ton serveur Unraid où tourne le conteneur Ollama, p. ex. http://192.168.1.10:11434.
4. Compose Up. Loki est accessible sur http://<ip-unraid>:8717 (change le port à gauche du mapping 8717:8080 s'il est déjà pris).

La première publication de l'image prend quelques minutes (le temps que le workflow GitHub se termine). Si l'image est privée, rends le package public une fois (GitHub → Packages → loki → Package settings → Change visibility).

Les modèles déjà présents dans ton Ollama sont détectés automatiquement ; tu peux en télécharger d'autres depuis l'onglet Configuration. Mise à jour : Compose Down/Up (avec pull), ou docker compose pull.

Développement (sans Docker)

Backend

cd backend
pip install -r requirements.txt
OLLAMA_HOST=http://localhost:11434 uvicorn app.main:app --reload --port 8080

Frontend (proxy /api → :8080)

cd frontend
npm install
npm run dev        # http://localhost:5173

Configuration (variables d'environnement)

Variable	Défaut	Rôle
OLLAMA_HOST	http://host.docker.internal:11434	URL de l'instance Ollama
DEFAULT_MODEL	llama3.1:8b	Modèle sélectionné au démarrage
WORKSPACE_DIR	/workspace	Dossier de travail de l'agent
DATA_DIR	/data	Base SQLite (sessions + config)
PORT	8717	Port de l'application (dedans = dehors)
SEARX_URL	(vide)	Instance SearxNG pour web_search (sinon DuckDuckGo)

Utilisation

1. Vérifie la pastille Ollama (verte = connecté) en haut à droite, et choisis un modèle qui supporte le function calling (ex. llama3.1:8b, qwen2.5-coder).
2. Décris une tâche dans le tchat, p. ex. « Crée une landing page pour un café nommé Café Lumière, avec menu et horaires ».
3. L'agent lit/écrit des fichiers dans le workspace ; chaque appel d'outil s'affiche dans le fil, et l'aperçu HTML apparaît à droite (onglets Aperçu / Code / Logs).
4. Règle le comportement dans Configuration (modèle, température/top-p/top-k, jetons max, outils actifs, invite système).

Outils de l'agent

Outil	Rôle	Par défaut
read_file	Lire un fichier du workspace	activé
write_file	Créer / modifier un fichier	activé
list_dir	Lister un répertoire	activé
web_search	Recherche web (DuckDuckGo / SearxNG)	désactivé
run_shell	Exécuter une commande (sensible)	désactivé

Auto-réglage GPU (« Réglage auto »)

Dans Configuration → Génération, le bouton ⚡ Réglage auto :

1. détecte le GPU (VRAM) via nvidia-smi/rocm-smi, ou la valeur déclarée GPU_VRAM_MB ;
2. lit les métadonnées du modèle sélectionné via Ollama (contexte max, architecture, taille, quantization) ;
3. calcule la fenêtre de contexte (num_ctx) la plus grande qui tient en VRAM (estimation du cache KV) et un nombre de jetons max cohérent, puis les applique ;
4. vérifie le placement réel du modèle via /api/ps d'Ollama (GPU / CPU).

Ollama distant : si Ollama tourne sur une autre machine que Loki, la détection nvidia-smi ne voit pas ce GPU. Déclare alors la VRAM avec GPU_VRAM_MB (ex. 12000 pour une carte 12 Go) pour un réglage précis.

Pourquoi c'est utile : un num_ctx trop grand fait déborder le modèle sur le CPU (lent). En l'ajustant à ta VRAM, le modèle reste sur le GPU. Laisse num_ctx = 0 (auto) pour utiliser le défaut du modèle.

Sécurité

• Confinement : toutes les opérations fichier (read_file, write_file, list_dir) et run_shell sont strictement confinées au WORKSPACE_DIR. Toute tentative de sortie (../, chemin absolu) est rejetée.
• run_shell est désactivé par défaut. Une fois activé, chaque commande proposée par l'agent demande une validation explicite dans l'interface (option confirm_shell, activée par défaut) avant exécution.
• Le conteneur tourne en utilisateur non-root et expose un HEALTHCHECK.
• Loki est conçu pour un usage local : n'expose pas le port publiquement sans ajouter ta propre couche d'authentification.

Feuille de route

• Phase 1 — Socle + design system fidèle au thème, layout 3 panneaux
• Phase 2 — Connexion Ollama : statut, liste des modèles, pull avec progression, sélecteur
• Phase 3 — Chat streaming (SSE) + persistance des sessions (SQLite)
• Phase 4 — Boucle agentique & outils fichiers (read/write/list), confinés au workspace, rendu des appels d'outils dans le fil
• Phase 5 — Aperçu HTML live + onglets Code/Logs + arborescence du workspace
• Phase 6 — Configuration complète (génération, toggles d'outils, invite système)
• Phase 7 — Outils avancés : web_search (DuckDuckGo/SearxNG) et run_shell avec validation utilisateur
• Phase 8 — Durcissement & documentation Docker

Structure

backend/   FastAPI : routes Ollama, client httpx, config
frontend/  React : design system (tailwind.config), panneaux, store Zustand
workspace/ fichiers créés par l'agent (monté en volume)
data/      base SQLite (monté en volume)