Loki/README.md

Loki — assistant IA local en conteneur (fork d'AJEAN)

Loki est un fork de AJEAN de nathaninline, sous licence MIT — voir NOTICE.md et LICENSE. L'essentiel du code et des fonctionnalités vient d'AJEAN ; ce fork le rebaptise et le fait tourner dans un conteneur Docker GPU autonome, là où l'amont s'installe en binaire + systemd sur la machine hôte.

Loki fait tourner un modèle de langage 100 % en local : discussions multiples, mémoire persistante, accès internet, captures de pages web, outils MCP, agent (shell, fichiers) — serveur d'inférence llama.cpp compris, dans une seule image.

Architecture

┌────────────────── conteneur loki ──────────────────┐
│  loki web  (UI + API, port 8090, premier plan)     │
│     │ pilote (fichier PID — pas de systemd)        │
│  loki serve ──exec──► llama-server (CUDA, :8080)   │
│                        ▲ modèles .gguf             │
│  chromium (Playwright) — captures de pages web     │
│  /data (config, bbolt, presets, mémoire,           │
│         workspace par discussion, modèles)         │
│  /models (GGUF déposés à la main)                  │
└────────────────────────────────────────────────────┘

• Un seul conteneur : l'UI joint le moteur sur localhost (contrainte héritée de l'amont), les deux partagent donc le même conteneur.
• Sans systemd : l'amont pilote le moteur via systemctl ; en conteneur, Loki bascule automatiquement sur une supervision par fichier PID (internal/loki/sys_service_container.go). Changer de modèle depuis l'UI redémarre le moteur normalement.
• Le moteur (port 8080, non authentifié par défaut) n'est pas exposé ; seule l'UI (8090) l'est.

Démarrage rapide (Docker, GPU NVIDIA)

Pré-requis : pilote NVIDIA + NVIDIA Container Toolkit.

cp .env.example .env
docker compose up --build   # quelques minutes : llama-server vient précompilé
                            # de l'image officielle llama.cpp (server-cuda)

Interface : http://localhost:8090 — installe un modèle depuis la recherche Hugging Face intégrée (voir ci-dessous), il démarre tout seul.

Installer un modèle

Dans l'éditeur de preset, Chercher un modèle interroge Hugging Face et ne remonte que les dépôts GGUF. Choisir un dépôt déplie ses quantifications avec leur taille et un verdict mémoire (ok / juste / trop) calculé sur la VRAM réellement détectée — ou sur la RAM système s'il n'y a pas de GPU. C'est une estimation : le coût exact du cache KV dépend de l'architecture du modèle, que la seule liste des fichiers ne révèle pas.

Si le dépôt publie un projecteur vision (mmproj-*.gguf), Loki propose de l'installer avec le modèle et remplit le champ Vision du preset. C'est le seul moyen fiable d'avoir la vision : un projecteur encode dans l'espace latent de son modèle, donc un mmproj pris dans un autre dépôt donne un moteur qui démarre et ne voit rien. Quand le dépôt n'en publie pas, Loki le dit plutôt que d'aller en chercher un ailleurs.

Deux repères pour choisir un dépôt :

• unsloth/* publie des quantifications Dynamic (UD-Q4_K_XL, UD-IQ3_XXS…) qui gardent en plus haute précision les tenseurs sensibles : à taille égale, elles se tiennent mieux qu'un Q4_K_M classique.
• ggml-org/* est le dépôt de référence de l'équipe llama.cpp — c'est en général là que le projecteur vision est publié en premier.

Le champ Télécharger un modèle reste disponible pour coller un lien direct (dépôt privé, fichier hors des conventions). Un dépôt à accès restreint demande la variable d'environnement HF_TOKEN.

Installation sur Unraid

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

1. Installe le plugin Nvidia Driver (Apps) et vérifie nvidia-smi.
2. Crée les dossiers :

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

3. Plugin Compose Manager → nouvelle stack → colle docker-compose.unraid.yml → Compose Up.
4. Interface : http://<ip-unraid>:8090.

Configuration

Tout se règle dans l'UI (modèle, contexte, presets…) et survit aux redémarrages (volume /data). Variables d'environnement du conteneur :

Variable	Rôle	Défaut
LOKI_WEB_PORT	port de l'UI	8090
LOKI_MODEL	modèle initial (semé au 1er boot seulement)	—
LOKI_CTX	taille de contexte initiale	32768
LOKI_NGL	couches GPU initiales	999 (tout)
LOKI_HOME	données (volume)	/data
LOKI_MODEL_DIRS	dossiers .gguf additionnels	/models
HF_TOKEN	jeton Hugging Face, pour les dépôts à accès restreint	—

En CLI dans le conteneur : docker exec -it loki loki status (aussi : logs, restart, config, bench, test…).

Données et persistance

Tout l'état vit sous /data (= LOKI_HOME). Si ce chemin n'est pas un volume monté sur l'hôte, il disparaît au premier docker compose down — presets et modèles compris.

Chemin	Contenu
/data/loki.db	base bbolt : préférences, discussions, mémoire des réglages
/data/presets/	un .env par preset (modèle, contexte, NGL, vision…)
/data/models/	modèles téléchargés depuis l'interface
/data/memory/	pages de mémoire persistante (.md)
/data/workspace/	racine du dossier de travail de l'agent
/data/workspace/discussions/<id>/	fichiers d'UNE discussion : dépôts, captures, ce que l'agent y écrit
/data/loki-engine.log	journal de llama-server (aussi via loki logs)
/models	GGUF déposés à la main depuis l'hôte (volume séparé, LOKI_MODEL_DIRS)

Vérifier que le volume est bien là :

docker inspect loki --format '{{range .Mounts}}{{.Source}} → {{.Destination}}{{println}}{{end}}'

Sur Unraid, garde le même chemin hôte d'un lancement à l'autre : /mnt/user/… (partage, via FUSE) et /mnt/cache/… (disque de cache) désignent des emplacements différents dès que le partage n'est pas en cache-only ou que le mover est passé. Le compose fourni utilise /mnt/user/appdata/loki/….

Tu perds modèles, discussions et fichiers à chaque redémarrage ? C'est le signe que /data n'est pas monté : le conteneur écrit alors dans sa couche éphémère, détruite à chaque recréation (mise à jour d'image, compose down, redémarrage de l'array). Vérifie avec la commande docker inspect ci-dessus : il doit y avoir une ligne … → /data et une … → /models. S'il n'y en a pas, ton conteneur a été lancé sans mapping (template Docker Unraid incomplet, docker run sans -v) — recrée-le avec les volumes du compose fourni. Depuis cette version, Loki le détecte au démarrage : bandeau rouge dans l'UI et avertissement en tête du journal du conteneur.

Autre piège au redémarrage du serveur : Docker relance les conteneurs restart: unless-stopped avant que le plugin Nvidia Driver ait chargé ses modules. Le journal montre alors des ERROR: init … result=11 et le moteur démarre sans GPU. Un docker restart loki une fois le pilote prêt suffit.

Fonctionnalités

Héritées d'AJEAN :

• Tchat avec streaming, raisonnement visible, pièces jointes, export de conversations. La vision demande un modèle multimodal et son projecteur mmproj — voir Installer un modèle.
• Mémoire persistante (memory off|ondemand|always).
• Accès internet : recherche + lecture de pages, moteur Go intégré ou Crawl4AI pour les pages JS.
• Agent : shell, fichiers, workspace (agent on).
• Serveurs MCP : Node.js (npx) et uv (uvx) sont inclus dans l'image, pour les serveurs écrits en JavaScript comme en Python. Au premier lancement, npx/uvx téléchargent le paquet du serveur — Loki attend jusqu'à 3 minutes ce coup-là (au lieu d'échouer sur « context deadline exceeded ») ; les lancements suivants partent du cache en quelques secondes.
• Presets de configuration par modèle, bench, auto-détection GPU.
• API OpenAI-compatible exposable, protégée par clé (voir ci-dessous — ce fork la sert autrement que l'amont).

Ajoutées par ce fork :

• Mode Code : chaque discussion a un sélecteur Chat | Code dans le pied de la carte de saisie. En mode Code, Loki devient un agent de code : outils read/grep/glob (lecture bornée, numéros de ligne — et un fichier doit avoir été LU avant d'être modifié), outils git (git_status, git_diff, git_clone — le clone atterrit dans le dossier de la discussion), jobs d'arrière-plan (bash_bg/bash_tail pour un serveur de dev ou un build long), et critères d'acceptation : le modèle pose le contrat (2-6 critères testables, éditables dans le panneau au-dessus de la saisie), puis une passe de vérification indépendante — même modèle, contexte isolé, seule habilitée à marquer un critère « passé » — contrôle le diff et relance la correction jusqu'à ce que tout passe (2 corrections max). Les fichiers modifiés passent au LSP (gopls, typescript-language-server, pyright — inclus dans l'image) : les erreurs de compilation reviennent dans le résultat de l'outil, sans lancer de build. Sécurité : commandes catastrophiques refusées (rm -rf /, mkfs, reboot…), chemins bornés au dossier de la discussion en mode Code. En mode Chat, un message qui ressemble à une tâche de code fait apparaître une puce « passer en mode Code ? » — suggestion, jamais bascule automatique. Conception reprise d'OpenFox (MIT), réécrite en Go — voir NOTICE.md.
• Catalogue MCP : le panneau Serveurs MCP offre un bouton catalogue — une vingtaine de serveurs connus (filesystem, git, fetch, memory, sqlite, playwright, context7, github…) avec leur commande déjà renseignée, classés par catégorie. Choisir une entrée n'installe rien : ça remplit le formulaire d'ajout, tu relis la commande — qui s'exécutera sur cette machine — puis tu enregistres. Le catalogue est un JSON embarqué dans le binaire (internal/loki/mcp_catalog.json), donc aucun appel à un annuaire distant : pour en proposer d'autres, édite ce fichier et recompile. Une entrée dont le runtime manque (npx/uvx absent) le signale au lieu d'échouer plus tard, et celles qui réclament une clé d'API la rappellent avant l'enregistrement.
• Intensité du raisonnement : un niveau — auto / aucune / basse / moyenne / haute — envoyé à llama-server comme reasoning_effort. Réglable dans la barre de saisie, parce que ça se décide en écrivant le message : le changement s'applique au message suivant, sans redémarrer le moteur. L'éditeur de preset garde le même réglage comme défaut du modèle ; appliquer un preset reprend donc la main sur le choix fait à la volée. none coupe le raisonnement ; les autres valeurs sont passées au gabarit jinja du modèle, ce qui ne change le comportement que des modèles qui les lisent (gpt-oss et apparentés) — ailleurs c'est ignoré sans erreur, et l'interface le dit plutôt que de promettre un effet. La liste est grisée quand le raisonnement est coupé pour ce modèle.
• Discussions multiples : historique complet dans la barre latérale, titre repris du premier message (renommable), suppression. Chaque discussion a son dossier de fichiers (workspace/discussions/<id>/) : les pièces jointes déposées, les captures et ce que l'agent écrit y atterrissent, le shell et les chemins relatifs du modèle y sont résolus. Changer de discussion change donc les fichiers ; supprimer (ou vider) une discussion emporte les siens, pour que le disque ne se remplisse pas en silence.
• Recherche Hugging Face intégrée avec verdict mémoire et installation liée du projecteur vision (voir Installer un modèle).
• Captures de pages web : l'agent dispose de l'outil web_screenshot (Chromium via Playwright, inclus dans l'image). Les captures partent en JPEG et sont plafonnées à 20 fichiers / 40 Mo par discussion. La description de l'outil suit la capacité réelle du moteur, sondée sur /props : sans vision effective, elle dit au modèle « tu ne vois pas l'image » plutôt que de lui promettre des yeux qu'il n'a pas — il peut toujours prendre la capture et la montrer, sans prétendre la décrire. L'image relayée au moteur reste éphémère : la persister gonflait le contexte jusqu'à le faire déborder.
• Panneau Fichiers (bouton dossier de la barre de saisie) : les fichiers de la discussion ouverte — dépôts, captures, ce que l'agent y a écrit — avec navigation dans les sous-dossiers, téléchargement et suppression. Un dossier affiche la taille de tout son contenu, c'est ce qu'on libère en le supprimant, et le pied donne l'occupation disque de la discussion. Les chemins sont bornés à son dossier, liens symboliques résolus des deux côtés : ni le reste du disque ni les autres discussions ne sont atteignables. Les fichiers d'avant ce rangement que la migration n'a pas su rattacher restent joignables par le bouton hors discussion, qui disparaît une fois le ménage fait.
• Interface « Sober Tech » : ardoise et sauge, typographie Inter (interface) et JetBrains Mono (code, chiffres, chemins) — embarquées dans le binaire, donc aucune requête vers un service de polices. Deux variantes : claire par défaut, Deep Dark (fond #0F172A, cartes #1E293B) d'un clic depuis l'en-tête. L'en-tête porte le titre de la discussion et le sélecteur de modèle (le changement de preset ne demande plus d'ouvrir les réglages) ; la barre latérale s'escamote pour rendre toute la largeur au fil ; les discussions s'y cherchent au clavier et les jauges GPU / VRAM / mémoire vive restent visibles en pied de colonne.
• API OpenAI servie par Loki : /v1/* est exposé sur le port de l'interface (8090) et relayé vers llama-server, au lieu d'annoncer l'adresse du moteur. Conséquence directe : l'API est joignable partout où l'interface l'est — par l'IP du réseau local comme par un nom de domaine — sans publier de second port ni ouvrir le moteur. L'amont annonçait http://<ip>:8080/v1, une adresse injoignable en conteneur (le port 8080 n'y est pas publié, et l'IP détectée est celle du bridge Docker).
  • Authentification par la clé API du panneau (Authorization: Bearer …), vérifiée par Loki et par le moteur. Sans clé, l'endpoint est ouvert et l'interface le dit en rouge.
  • Adresse publique : un champ où saisir son domaine, pour le cas du reverse proxy où Loki ne voit qu'un appel interne. Laissé vide, l'adresse affichée suit celle du navigateur.
  • TLS : mettre un reverse proxy devant (Caddy, Nginx, Traefik). Loki honore X-Forwarded-Proto pour annoncer une adresse en https.
  • L'ancienne exposition publique via le relais de l'amont (<machine>.oai.ajean.link) est retirée de l'interface : elle exigeait un jeton de relais que ce fork ne permet plus d'obtenir, l'interrupteur ne pouvait donc qu'échouer.
• Budget d'appels d'outils : un tour d'agent n'a aucun plafond — couper une recherche légitime est pire que la laisser durer — mais au-delà de 24 appels sur un même tour, Loki rappelle au modèle combien il en a déjà faits et lui demande de conclure. Le rappel revient tous les 24 appels, en durcissant le ton ; il ne coupe jamais le tour, c'est de la pression, pas une barrière. Sans lui, un petit modèle qui tourne en rond n'avait rien en face de lui sauf le bouton stop (vu en production : 50 appels, 55 minutes, à relire cinq fois les mêmes fichiers). Réglable par AGENT_BUDGET dans config.env — AGENT_BUDGET=off le désactive complètement.
• Identité : ton prénom et un avatar emoji pour toi et pour Loki, affichés dans le fil.
• Paramètres : les réglages d'application (identité, apparence, accès OpenAI, actions) sont regroupés à part des réglages d'IA.

Retirées par ce fork :

• Accès distant via ajean.link : la section de l'interface et son module JS sont supprimés — un conteneur derrière son propre réseau n'en a pas l'usage. Le code serveur du relais reste en place mais inerte (aucun jeton, aucune section pour en fournir un) : le retirer créerait un conflit à chaque reprise de l'amont.
• Postes distants (faire agir l'agent sur un autre PC appairé) : bouton du composeur, modales d'appairage et module JS supprimés. Même traitement que ci-dessus — les routes /api/node/* subsistent mais plus rien ne peut générer de code d'appairage, donc aucun poste ne peut se connecter.
• Catalogue de modèles distant : il interrogeait ajean.link/models.json, sa route n'avait aucun consommateur et son repli embarqué datait de 2024. La recherche Hugging Face le remplace.

Différences avec l'amont

	AJEAN (amont)	Loki (ce fork)
Installation	binaire + sudo ajean install (systemd)	docker compose up
Moteur llama.cpp	compilé sur la machine (ajean llamacpp install)	image officielle llama.cpp (server-cuda), précompilée
Panneau « Moteur »	propose d'installer/compiler	affiche la version qui tourne et la met à jour en un clic (sans rebuild)
Supervision moteur	systemd / launchd / PID (Windows)	fichier PID (LOKI_CONTAINER=1)
Configuration initiale	ajean edit ($EDITOR)	entrypoint + loki config set
Choix du modèle	lien Hugging Face collé à la main	recherche intégrée + verdict VRAM + projecteur lié
Historique de tchat	conversation unique	discussions multiples, titrées et persistées
Agent de code	—	mode Code : critères d'acceptation, passe de vérification, LSP, outils git
Accès distant	relais chiffré ajean.link	retiré de l'interface
Endpoint OpenAI	:8080/v1 du moteur, ouvert par network on	/v1 servi par Loki sur le port de l'interface, protégé par la clé API
Mise à jour	ajean update (binaire GitHub)	docker compose pull

Le reste — mémoire, outils, protocole, moteur d'inférence — est celui d'AJEAN. Pour récupérer les évolutions de l'amont :

git fetch upstream && git merge upstream/main   # conflits de renommage à arbitrer

Build sans GPU / autres accélérateurs / version épinglée

L'image Loki se construit au-dessus de l'image serveur officielle de llama.cpp, choisie par le build-arg LLAMACPP_IMAGE :

# CPU seul (test sans GPU)
docker build --build-arg LLAMACPP_IMAGE=ghcr.io/ggml-org/llama.cpp:server .
# Vulkan (GPU AMD/Intel/NVIDIA sans CUDA)
docker build --build-arg LLAMACPP_IMAGE=ghcr.io/ggml-org/llama.cpp:server-vulkan .
# Version de llama.cpp épinglée (reproductible)
docker build --build-arg LLAMACPP_IMAGE=ghcr.io/ggml-org/llama.cpp:server-cuda-b10423 .

Aucune compilation de llama.cpp n'a lieu : le moteur est maintenu et précompilé par l'équipe amont (toutes architectures GPU courantes).

Mettre à jour llama.cpp sans reconstruire l'image

llama.cpp publie plusieurs versions par jour ; l'image de Loki, elle, ne se reconstruit qu'à une mise à jour de Loki. Le moteur y était donc figé à la date du dernier build, et le rattraper imposait un rebuild complet (2,6 Go) pour un composant de 170 Mo.

Réglages → Moteur affiche désormais la version de llama.cpp qui tourne (b10450, avec son commit) et deux boutons :

• vérifier la version — interroge le registre et dit s'il existe plus récent ;
• mettre à jour le moteur — télécharge llama-server et ses bibliothèques depuis l'image officielle, ghcr.io/ggml-org/llama.cpp:server-cuda.

Ce qui est téléchargé n'est pas l'image : un manifeste OCI liste ses couches, et seules celles qui portent /app sont récupérées (~170 Mo). Le runtime CUDA (2 Go) et la base système sont déjà dans l'image de Loki. Le moteur atterrit dans /data/engine/<version>/, donc sur le volume de données : il survit à un docker compose pull.

La variante est déduite du moteur en place (CUDA, Vulkan, SYCL, MUSA ou CPU) : une installation Vulkan ne se verra jamais proposer une image CUDA.

Le garde-fou. La mise à jour apporte llama.cpp, pas le runtime CUDA, qui reste celui de l'image. Un llama.cpp compilé pour un CUDA plus récent ne chargerait pas son backend GPU ici — et le symptôme serait silencieux : tout fonctionne, mais sur le processeur. Le nouveau moteur est donc lancé à blanc avant toute bascule ; s'il ne démarre pas, ou s'il ne voit plus aucune carte alors que le moteur courant en voyait, la mise à jour est refusée et le moteur courant n'est pas touché. Le moteur livré par l'image reste par ailleurs intact : revenir au moteur de l'image y ramène en un clic, sans réseau.

Quand cette limite est atteinte pour de bon (CUDA majeur trop ancien), la solution reste le rebuild avec un LLAMACPP_IMAGE récent, ci-dessus.

Derrière un miroir de registre ou un réseau qui n'atteint pas ghcr.io : LOKI_OCI_REGISTRY=https://mon-miroir.interne dans l'environnement du conteneur.

Licence

MIT — © les contributeurs d'AJEAN (« Jean contributors ») pour le code amont, voir LICENSE et NOTICE.md.