Loki — assistant IA local en conteneur (fork d'AJEAN)
Loki est un fork de AJEAN de nathaninline, sous licence MIT — voir
NOTICE.mdetLICENSE. 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 : tchat, mémoire persistante, accès internet, outils MCP, agent (shell, fichiers), accès distant chiffré — 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 │
│ /data (config, bbolt, mémoire, workspace) │
│ /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'unQ4_K_Mclassique.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.
- Installe le plugin Nvidia Driver (Apps) et vérifie
nvidia-smi. - Crée les dossiers :
mkdir -p /mnt/user/appdata/loki/data /mnt/user/appdata/loki/models - Plugin Compose Manager → nouvelle stack → colle
docker-compose.unraid.yml→ Compose Up. - 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 |
En CLI dans le conteneur : docker exec -it loki loki status (aussi :
logs, restart, config, bench, test…).
Fonctionnalités (héritées d'AJEAN)
- Tchat avec streaming, raisonnement visible, pièces jointes, vision (selon modèle), export de conversations.
- 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 est inclus dans l'image pour les serveurs
npx. - Presets de configuration par modèle, bench, auto-détection GPU.
- Accès distant chiffré via le relais ajean.link (service opéré par l'auteur de l'amont).
- API OpenAI-compatible exposable (
network on, protégée par clé).
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 |
| Supervision moteur | systemd / launchd / PID (Windows) | fichier PID (LOKI_CONTAINER=1) |
| Configuration initiale | ajean edit ($EDITOR) |
entrypoint + loki config set |
| Mise à jour | ajean update (binaire GitHub) |
docker compose pull |
Le reste — UI, mémoire, outils, protocole — 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).
Licence
MIT — © les contributeurs d'AJEAN (« Jean contributors ») pour le code amont,
voir LICENSE et NOTICE.md.