Akan

# AKAN Framework [](./LICENSE) [](#) [](#) > **Gardez vos données privées. Gardez votre liberté de choix.** AKAN est un framework d'assistant IA self-hosted conçu autour d'une idée simple : votre LLM tourne sur votre propre machine, vos conversations ne quittent jamais votre infrastructure — mais vous pouvez aussi, quand vous le souhaitez, utiliser les meilleurs modèles cloud (OpenAI, Anthropic, Google…) via vos propres clés API, sans intermédiaire. Vos données restent chez vous. Vos clés API sont chiffrées AES-256. Rien n'est transmis à un tiers sans votre accord explicite. > **Inspiré du projet [Kiro](https://www.renaud-dekode.fr/c/kiro) de [Renaud Dékode](https://www.renaud-dekode.fr) et de sa communauté privée des « Malinos ».** > Merci pour l'idée fondatrice : un assistant personnel, souverain, sans compromis. > > *À ne pas confondre avec [Kiro de AWS](https://github.com/kirodotdev/Kiro), un IDE agentique sans lien avec ce projet.* **Intégration MCP (Model Context Protocol)** : connectez n'importe quel serveur MCP à AKAN pour étendre ses capacités (outils, accès fichiers, APIs tierces…). Les agents IA autonomes ne sont pas encore intégrés. ⚠️ **AKAN s'utilise EXCLUSIVEMENT derrière un VPN privé (Tailscale ou Headscale). Ne PAS exposer ces services sur internet public.** --- ## Fonctionnalités - Interface chat universelle (SPA web, sans framework JS) - Inférence locale via llama.cpp TurboQuant (modèles GGUF Qwen3.5 + Heretic) - Connexion aux API LLM cloud (OpenAI, Anthropic, Google, Mistral, Perplexity, DeepSeek, Grok…) - Clés API chiffrées AES-256-GCM — jamais stockées en clair - Recherche web intégrée (SearXNG, 100% self-hosted) - Génération d'images (cloud + Pollinations local) - Audio STT/TTS (Whisper + Piper VITS via Sherpa-ONNX) - Support MCP (Model Context Protocol) — serveurs stdio et HTTP - Statistiques d'usage et budget par provider - Persistance JSON simple — pas de base de données relationnelle - Backup automatique du storage --- ## Pour les non-développeurs — Guide d'installation pas à pas > Pas besoin de savoir coder. Il vous faut juste un VPS Linux (serveur cloud) et 20 minutes. ### Ce dont vous avez besoin - Un **VPS Linux** avec au moins 8 Go de RAM (OVH, Hetzner, Scaleway…) — comptez ~5-10 €/mois - **Docker** installé sur ce VPS ([guide officiel](https://docs.docker.com/engine/install/)) - **Tailscale** installé sur le VPS ET sur vos appareils ([tailscale.com](https://tailscale.com)) — gratuit pour usage personnel - Un terminal (ligne de commande) — sur Windows : PowerShell ou [Windows Terminal](https://aka.ms/terminal) ### Étape 1 — Connectez-vous à votre VPS ```bash ssh root@<IP_DE_VOTRE_VPS> ``` ### Étape 2 — Récupérez AKAN ```bash git clone https://github.com/librariums/akan.git cd akan ``` ### Étape 3 — Créez votre fichier de configuration ```bash cp .env.example .env ``` Maintenant éditez ce fichier `.env` avec vos valeurs : ```bash nano .env ``` **Les 4 secrets à générer** (copiez-collez chaque commande, puis copiez le résultat dans `.env`) : ```bash # Pour HMAC_SALT, ADMIN_PASSPHRASE, SEARX_SECRET : openssl rand -hex 32 # Pour REDIS_PASSWORD (16 caractères suffisent) : openssl rand -hex 16 ``` **Votre IP Tailscale** (à noter dans `TAILSCALE_IP=`) : ```bash tailscale ip -4 ``` > ⚠️ **HMAC_SALT est le plus important** : il chiffre toutes vos clés API stockées. Si vous le perdez ou le changez, vos clés deviennent illisibles. Notez-le quelque part hors du VPS (gestionnaire de mots de passe, papier…). ### Étape 4 — Créez les dossiers nécessaires ```bash mkdir -p storage/models storage/slots storage/redis storage/certs \ storage/editable storage/media \ logs/inference logs/app logs/audio logs/audit ``` ### Étape 5 — Générez votre certificat de sécurité (HTTPS) ```bash openssl req -x509 -newkey rsa:4096 -nodes \ -keyout storage/certs/key.pem \ -out storage/certs/cert.pem \ -days 365 \ -subj "/CN=$(grep '^TAILSCALE_IP=' .env | cut -d= -f2)" chmod 600 storage/certs/key.pem ``` ### Étape 6 — Téléchargez un modèle IA local Choisissez un modèle selon votre RAM disponible (voir tableau dans la section [Modèles supportés](#modèles-supportés)) : ```bash # Exemple — Crow 4B en Q5_K_M (~2.9 Go, recommandé pour 8 Go de RAM) : wget -P storage/models/ \ https://huggingface.co/mradermacher/Crow-4B-Opus-4.6-Distill-Heretic_Qwen3.5-GGUF/resolve/main/Crow-4B-Opus-4.6-Distill-Heretic_Qwen3.5.Q5_K_M.gguf ``` Puis renseignez le nom exact du fichier dans `.env` : ``` MODEL_FILE=Crow-4B-Opus-4.6-Distill-Heretic_Qwen3.5.Q5_K_M.gguf ``` > Les URLs des modèles testés sont dans [`models/catalog.json`](./models/catalog.json). ### Étape 7 — Lancez AKAN ```bash # ⚠️ Ce build compile le moteur d'inférence pour VOTRE CPU — peut prendre 10-20 min docker compose build akan-inference # Lance tous les services docker compose up -d # Vérifiez que tout est en marche (attendez 2-3 min le premier démarrage) docker compose ps ``` ### Étape 8 — Accédez à l'interface Ouvrez votre navigateur sur l'appareil relié à Tailscale : ``` https://<VOTRE_IP_TAILSCALE> ``` Le navigateur affichera un avertissement "connexion non sécurisée" — c'est normal pour un certificat auto-signé en réseau privé. Cliquez sur "Avancé" puis "Continuer". ### Étape 9 (optionnel) — Ajoutez des clés API cloud Si vous voulez aussi utiliser OpenAI, Anthropic, Google Gemini, Mistral… en plus de votre LLM local : 1. Dans l'interface AKAN, cliquez sur l'icône **Admin** (en haut à droite, mot de passe = `ADMIN_PASSPHRASE` du `.env`) 2. Onglet **Clés API** → choisissez le provider → collez votre clé 3. La clé est immédiatement chiffrée AES-256-GCM côté serveur, jamais stockée en clair Vous pouvez ensuite basculer entre votre LLM local et les modèles cloud dans le sélecteur en haut de la conversation. ### Mise à jour d'AKAN Quand de nouvelles versions sortent sur GitHub : ```bash cd /chemin/vers/akan git pull origin main # Si le code applicatif a changé (le plus fréquent) — redémarre les services : docker compose up -d # Si le Dockerfile inference a changé (rebuild nécessaire) : docker compose build --no-cache akan-inference docker compose up -d --force-recreate akan-inference ``` > Vos conversations, mémoires, clés API et stats sont conservées dans `storage/` (gitignored) — aucune perte de données lors des mises à jour. --- ## Pour les développeurs ### Architecture 8 services Docker orchestrés via docker-compose : | Service | Rôle | Port interne | |---|---|---| | `akan-app` | Backend Node.js / Express + SPA | 3000 | | `akan-inference` | llama.cpp TurboQuant (`feature/turboquant-kv-cache`) | 8080 | | `akan-audio` | Sherpa-ONNX STT/TTS (FastAPI) | 8082 | | `akan-proxy` | nginx TLS (terminaison SSL) | 443 | | `akan-redis` | Cache + sessions | 6379 | | `akan-search` | SearXNG (moteur de recherche privé) | 8080 | | `akan-socket-proxy` | Docker socket sécurisé (read-only) | — | | `akan-rescue` | nginx fallback (accès admin si app down) | 9443 | ### Stack technique - **Backend** : Node.js / Express, sans ORM, sans framework frontend - **Stockage** : fichiers JSON atomiques (`tmp` + `rename`), pas de BDD relationnelle - **Chiffrement** : AES-256-GCM + PBKDF2 (clés API), HMAC-SHA256 (tokens) - **Logging** : LogTape (structuré, redaction automatique des secrets) - **Inférence** : fork llama.cpp [`feature/turboquant-kv-cache`](https://github.com/TheTom/llama-cpp-turboquant) compilé `GGML_NATIVE=ON` - **Sécurité périmètre** : Tailscale CGNAT (100.64.0.0/10), SSRF guard, rate-limit DNS ### Variables d'environnement clés Voir [`.env.example`](./.env.example) — toutes les variables sont documentées avec leur rôle, leurs valeurs par défaut et les commandes de génération. ### Développement local ```bash # Cloner et installer les dépendances git clone https://github.com/librariums/akan.git cd akan/app npm install # Lancer uniquement l'app (les services Docker annexes doivent tourner) NODE_ENV=development npm start ``` ### Structure du projet ``` akan/ ├── app/ # Backend Node.js │ ├── routes/ # Handlers Express (proxy, crud, stats, mcp…) │ ├── lib/ # Modules métier (cloud-providers, local-tools, memory-store…) │ ├── utils/ # Utilitaires (storage, logger, ssrf-guard, crypto) │ └── public/ # SPA (HTML + JS + CSS vanilla) ├── inference/ # Dockerfile llama.cpp TurboQuant ├── audio/ # Dockerfile Sherpa-ONNX ├── config/ # Configurations SearXNG, nginx ├── models/ # catalog.json (liste des modèles testés) ├── storage/ # Données persistantes (gitignored) └── docker-compose.yml ``` ### MCP (Model Context Protocol) AKAN supporte les serveurs MCP **stdio** et **HTTP**. Les outils MCP sont exposés au modèle **uniquement sur demande explicite** de l'utilisateur (pas d'auto-trigger, pas de pollution du contexte par défaut). **Pour ajouter un serveur MCP** : 1. Interface Admin → onglet **MCP Servers** 2. Indiquer le nom + la commande (stdio) ou l'URL (HTTP) 3. Sauvegarder, puis dans la conversation activer le toggle MCP + cocher les serveurs voulus **Exemple — Context7 (docs librairies à jour)** : ``` Nom : context7 Type : stdio Commande: npx Args : -y @upstash/context7-mcp@latest ``` Les outils MCP exposés sont préfixés `mcp_<server>_<tool>` (ex: `mcp_context7_get-library-docs`). Le modèle local et les modèles cloud (qui supportent le tool calling) peuvent tous les appeler. --- ## Modèles supportés Catalogue complet : [`models/catalog.json`](./models/catalog.json) Modèles testés — tous **Qwen3.5 + Heretic** (compatibles `--reasoning-format deepseek`) : | Modèle | Paramètres | Format recommandé | RAM modèle | RAM totale min | |---|---|---|---|---| | Crow 4B | 4B | Q8_0 (4.3 Go) | 4.5 Go | 8 Go | | Crow 9B | 9B | Q5_K_M (6.5 Go) | 6.5 Go | 12 Go | | Qwen3.5-27B Heretic v2 | 27B | Q4_K_M (15.4 Go) | 15.4 Go | 24 Go | > ⚠️ `--reasoning-format deepseek` est configuré dans `docker-compose.yml`. Les modèles non-Qwen3.5 (Llama, Mistral, Gemma…) peuvent nécessiter une adaptation. --- ## Sécurité AKAN est conçu pour un usage **exclusivement derrière un VPN privé**. La surface d'attaque est délibérément réduite à zéro depuis internet. Points clés : - Clés API chiffrées AES-256-GCM au repos - SSRF guard (blocage RFC1918, CGNAT, métadonnées cloud, rate-limit DNS) - Comparaisons timing-safe (anti timing-attack) - Stockage atomique (pas de corruption partielle) - Docker socket en lecture seule via `socket-proxy` Pour reporter une vulnérabilité : [SECURITY.md](./SECURITY.md) --- ## Tailscale vs Headscale **Tailscale** est le moyen le plus simple (gratuit pour usage personnel). **[Headscale](https://github.com/juanfont/headscale)** est l'alternative 100% open-source auto-hébergée, compatible avec tous les clients Tailscale officiels. ```bash # Démarrage rapide Headscale (sur un second VPS ou la même machine) docker run -d --name headscale \ -v ./headscale-config:/etc/headscale \ -p 8080:8080 \ headscale/headscale:latest ``` Documentation : <https://headscale.net> --- ## Contribuer Voir [CONTRIBUTING.md](./CONTRIBUTING.md). ## Changelog Voir [CHANGELOG.md](./CHANGELOG.md). ## Licence MIT — voir [LICENSE](./LICENSE).