skorokithakis/stavrobotUn assistant personnel IA axé sur la sécurité.
Stavrobot est un assistant IA personnel construit avec le principe de « tout l'accès dont un assistant IA a besoin, et rien de plus ».
Il possède toutes les fonctionnalités agréables d'un assistant IA, mais se concentre sur le sandboxing, l'isolation et les permissions minimales. Il est léger et se déploie avec seulement un docker compose up.
uv, isolé de l'environnement hôte.Installation assistée par IA : Dites à votre IA de codage (Claude Code, Cursor, Windsurf, etc.) de récupérer et de suivre https://stavrobot.stavros.io/INSTALL.md — elle vous guidera tout au long de la configuration de manière interactive.
Installation manuelle :
Envoyez un message à @BotFather sur Telegram pour créer un bot et copier le token. Envoyez un message à @userinfobot pour obtenir votre ID utilisateur Telegram (cet ID est utilisé comme chat ID).
Copiez env.example vers .env et changez POSTGRES_PASSWORD en quelque chose de sécurisé et TZ pour votre fuseau horaire.
Copiez config.example.toml vers data/main/config.toml et remplissez les champs obligatoires : apiKey, password, publicHostname, [owner].name, [owner].telegram (votre chat ID), et [telegram].botToken. Tout le reste dans le fichier est facultatif.
docker compose up --build
C'est tout. Envoyez un message à votre bot sur Telegram et il répondra. Voir les sections de configuration détaillées ci-dessous pour Signal, WhatsApp, email et autres options.
config.example.toml vers data/main/config.toml.authFile (ou apiKey) et publicHostname. Tout le reste est facultatif.env.example vers .env et définissez votre fuseau horaire (TZ). Les identifiants PostgreSQL et autres paramètres d'environnement peuvent également être remplacés ici. Définissez toujours POSTGRES_PASSWORD sur quelque chose de sécurisé — la valeur par défaut est un espace réservé faible et ne doit pas être utilisée en production.Stavrobot peut être pointé vers n'importe quel point de terminaison compatible OpenAI (Ollama, LiteLLM, vLLM, etc.) ou un proxy compatible Anthropic personnalisé en définissant baseUrl dans config.toml. Voir config.example.toml pour les champs obligatoires et les exemples de configuration.
L'application supporte deux modes d'authentification : clé API ou OAuth.
apiKey dans config.toml. Pas besoin de connexion ou déconnexion.authFile dans config.toml (un chemin où les identifiants seront stockés). La page de connexion fonctionne avec n'importe quel fournisseur OAuth supporté par Pi.
<votre-hôte>/login dans un navigateur. Suivez les instructions sur la page, et les identifiants sont sauvegardés dans le fichier d'authentification. Si l'authentification expire pendant que le bot est en cours d'exécution, il vous envoie un message avec l'URL de connexion via votre plateforme de messagerie.authFile. Le bot détectera l'absence d'identifiants au prochain message et vous invitera à vous connecter à nouveau.Le conteneur coder est optionnel (nécessaire uniquement pour la fonction d'auto-programmation). Il utilise Claude Code avec une authentification par abonnement (OAuth), séparée de la clé API de l'application principale.
Les profils Docker Compose sont séparés par des virgules, vous pouvez donc les combiner (par ex. COMPOSE_PROFILES=signal,coder).
COMPOSE_PROFILES dans votre fichier .env pour inclure coder (par ex. COMPOSE_PROFILES=coder, ou COMPOSE_PROFILES=signal,coder si vous utilisez également Signal).docker compose --profile coder up --builddocker compose exec -u coder coder claude (il vous demandera de vous connecter si ce n'est pas déjà fait).[coder].model dans votre config sur un alias de modèle Claude Code (sonnet, opus, ou haiku).Signal nécessite un numéro de téléphone séparé — pas votre numéro personnel. Une carte SIM prépayée ou un numéro VoIP fonctionne.
COMPOSE_PROFILES=signal dans votre fichier .env pour activer le conteneur signal-bridge.docker compose --profile signal builddocker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli link -n "Stavrobot" | tee >(xargs -L 1 qrencode -t utf8)' — scannez le code QR avec votre téléphone (Signal > Paramètres > Appareils liés).docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +VOTRE_NUMERO register', puis vérifiez avec docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +VOTRE_NUMERO verify CODE'.[signal].account dans votre config.docker compose up --build/settings.docker compose exec app node -e "fetch('http://localhost:3001/chat',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({message:'Send the message \"Hello from Stavrobot\" to my Signal number.'})}).then(r=>r.text()).then(console.log)"
[telegram].botToken dans votre config.[owner].telegram dans votre config./settings.WhatsApp nécessite un numéro de téléphone séparé, car sinon vous vous enverriez des messages à vous-même, ce qui ne fonctionne pas vraiment.
WhatsApp utilise Baileys, une bibliothèque WhatsApp Web non officielle qui se lie en tant qu'appareil compagnon (comme WhatsApp Web). Aucun numéro de téléphone séparé n'est nécessaire — il se lie à votre compte WhatsApp existant.
Risque : Baileys utilise une API non officielle. WhatsApp peut bannir les comptes qui l'utilisent. Utilisez à vos propres risques.
[whatsapp] à votre config.toml (voir config.example.toml pour le format).docker compose up --builddocker compose logs -f app)../data/whatsapp./settings.L'email utilise un Worker Cloudflare Email pour la livraison entrante et SMTP pour la sortie. Voir
config.example.toml pour le code complet du worker et les instructions détaillées de configuration.
[email] à votre config.toml avec les identifiants SMTP et un webhookSecret aléatoire.config.example.toml) et définissez les variables d'environnement WEBHOOK_URL et WEBHOOK_SECRET sur le worker./settings.docker compose up --build
L'API est disponible à http://localhost:10567/chat.
Remarque : Docker Compose expose l'application uniquement sur localhost:10567. Pour la rendre accessible de l'extérieur (nécessaire pour les webhooks Telegram/Signal et le paramètre publicHostname), mettez en place un proxy inverse (par ex. Nginx, Caddy) pointant vers localhost:10567. Vous pouvez également exposer le port directement, mais cela n'est pas recommandé car le trafic ne sera pas chiffré.
Nécessite Node.js >= 20 et une instance PostgreSQL en cours d'exécution.
npm install && npm run build && npm start
Remarque : L'exécution Python et l'intégration Signal fonctionnent uniquement à l'intérieur des conteneurs Docker.
Stavrobot dispose d'un système de connaissances à trois niveaux : les souvenirs, un bloc-notes et la base de données. Il les gérera assez bien tout seul, mais il est important que vous les connaissiez car vous voudrez aider le bot à les utiliser correctement.
Les souvenirs sont toujours injectés en bloc dans l'invite système. Vous devez être économe avec eux, car ils sont inclus dans le contexte à chaque fois, et en avoir beaucoup peut augmenter le contexte. Un exemple de bon souvenir serait « l'utilisateur préfère discuter dans un style informel. », quelque chose que le bot doit savoir à chaque fois, même si cela coûte en longueur de contexte supplémentaire.
Le bloc-notes est l'endroit où le bot garde les connaissances moins fréquemment consultées, mais qui concernent un sujet. Les entrées du bloc-notes ont un titre et un corps, et le titre est injecté automatiquement dans le contexte. Utilisez-le pour des choses importantes, mais moins souvent nécessaires, des choses qui se rapportent généralement à un sujet spécifique.
Par exemple, une bonne entrée de bloc-notes serait « préférences alimentaires », avec des détails sur ce que vous aimez manger, quand, etc. Le bot verra qu'il y a un sujet « préférences alimentaires », mais ne chargera pas le texte lui-même dans le contexte automatiquement, n'y accédant qu'à la demande.
Lorsque vous parlez au bot de nourriture, il saura qu'il y a une entrée de bloc-notes « préférences alimentaires » qu'il peut consulter, et le fera généralement tout seul.
La base de données est le troisième niveau, pour les données structurées ou en vrac qui n'ont pas leur place dans les souvenirs ou le bloc-notes. Le bot a un accès complet en lecture/écriture à PostgreSQL via SQL sans restriction, il peut donc créer des tables, exécuter des requêtes et stocker n'importe quoi. Utilisez-la pour des listes, des journaux, des enregistrements structurés, ou toute donnée qu'il est préférable de requêter que de lire en prose.
Le bot saura généralement assez bien quoi utiliser quand, mais parfois vous voudrez lui dire explicitement quelles informations mettre où.
Stavrobot peut envoyer des messages à des personnes en votre nom via Signal, Telegram, WhatsApp ou email. Besoin de planifier un dîner avec un ami ? Dites au bot de trouver un créneau qui convienne à vous deux, et il lui enverra un message, négociera une date et la mettra sur votre calendrier. Vous voulez organiser un rendez-vous, coordonner une sortie en groupe ou poser une question à quelqu'un pendant que vous êtes occupé ? Dites simplement au bot ce dont vous avez besoin et à qui parler.
Le bot lance un sous-agent dédié pour chaque conversation, avec ses propres instructions et contexte, afin de gérer les échanges avec l'autre personne sans encombrer votre chat principal. Lorsque la tâche est terminée, il désactive le contact et vous fait un rapport.
Pour garantir la sécurité, la messagerie nécessite deux choses avant que le bot puisse parler à quelqu'un :
/settings et ajoutez son numéro de téléphone (Signal ou WhatsApp) ou son chat ID (Telegram). C'est une étape unique par personne. Le bot ne peut pas modifier cette liste ni envoyer de message à quiconque n'y figure pas, quoi qu'il arrive.Un flux typique : vous ajoutez le numéro de téléphone de votre ami à la liste blanche via /settings une fois, puis dites au bot « trouve un créneau pour dîner avec Alex la semaine prochaine ». Le bot crée un enregistrement de contact pour Alex, lance un sous-agent, envoie un message à Alex sur Signal, fait des allers-retours pour trouver une date, et vous rapporte le résultat.
Les compétences sont des fichiers d'instructions en texte brut qui enseignent au bot de nouvelles capacités — des choses comme créer des tables, stocker des connaissances, créer des pages, ou suivre des flux de travail spécifiques. Ce ne sont pas du code ; ce sont des instructions en langage naturel que le bot lit et suit.
Pour installer le système de compétences, dites au bot de récupérer https://stavrobot.stavros.io/skills/bootstrap.md et de suivre ses instructions.
Une liste complète des compétences disponibles se trouve à https://stavrobot.stavros.io/skills/index.md. Pour installer une compétence, dites simplement au bot de la récupérer et de l'installer à partir de cette URL. Le bot vous montrera ce que fait la compétence et demandera confirmation avant de procéder.
Les fichiers de compétences se trouvent sur la branche pages de ce dépôt (servie via Cloudflare Pages). Pour contribuer une compétence, ajoutez un fichier Markdown dans skills/ sur cette branche. Chaque fichier de compétence comporte un en-tête YAML avec title, description, version, et un author optionnel, suivi des instructions en langage clair dans le corps. Voir SKILL-AUTHORING.md pour le guide complet de création. Soumettez une PR sur la branche pages.
Voir PLUGIN.md pour tout ce que vous devez savoir pour créer un plugin Stavrobot. Ce même document sert de référence pour les humains et les LLM.
Les plugins sont assez nécessaires pour activer les fonctionnalités de base du bot, comme la capacité d'« entendre » des notes vocales, d'envoyer des notes vocales, de connaître les lieux autour de vous, de rechercher sur le web, etc.
Ces capacités ne sont pas fournies d'emblée pour vous donner la possibilité de personnaliser votre bot comme vous le souhaitez. Vous devriez installer des plugins, sinon il vous manquera des fonctionnalités cruciales.
Vous pouvez trouver quelques plugins officiels ici :
Trois conteneurs Docker principaux : app (serveur TypeScript, expose POST /chat, gère les webhooks Telegram sur POST /telegram/webhook, gère les webhooks d'email entrants sur POST /email/webhook, et exécute WhatsApp en processus via Baileys), postgres (PostgreSQL 17 pour l'état persistant), et plugin-runner (serveur Node.js — liste, inspecte et exécute les plugins, qu'ils soient créés localement ou installés via git). Un conteneur optionnel coder (agent headless Claude Code pour créer et modifier des plugins modifiables) est activé via le profil Docker Compose coder. L'agent principal peut créer des sous-agents, chacun avec son propre historique de conversation, invite système et liste blanche d'outils. Les interlocuteurs sont des enregistrements de contact assignés aux agents pour le routage des messages entrants.