Stavrobot

Stavrobot est un assistant IA personnel conçu selon le principe « tous les 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 met l'accent sur le sandboxing, l'isolation et les permissions minimales. Il est léger et se déploie avec un simple docker compose up.

Fonctionnalités

• Sécurisé. Tout s'exécute dans un conteneur, votre OS hôte est totalement invisible pour l'IA. L'IA ne voit aucun secret, sauf si vous le souhaitez.
• Léger. Ne lance pas un conteneur par composant. Tous les plugins s'exécutent dans un seul conteneur, séparés par les permissions Unix.
• Utilisez le modèle que vous voulez. Local, OpenRouter, Anthropic/OpenAI. Tout ce que Pi prend en charge, le bot peut l'utiliser.
• Intégration Signal/Telegram/WhatsApp/Email. Messagerie bidirectionnelle, avec mise en forme, pièces jointes, etc.
• Intégration Pebble Index. Les enregistrements de bague peuvent être mis en file d'attente directement pour l'agent.
• Connaissances à trois niveaux. Se souvient de tout sans saturer son contexte. Récupère les données de sa mémoire de manière intelligente et transparente.
• Faible consommation de tokens. Diverses optimisations ont été apportées pour être économe en tokens. Il utilise même TOON en interne.
• Plugins. Installez des plugins et étendez les capacités de Stavrobot en lui donnant simplement une URL de dépôt git. Les plugins sont isolés les uns des autres — chacun s'exécute en tant qu'utilisateur système dédié, sans accès aux fichiers ni à la configuration des autres plugins.
• Sous-agents. L'agent principal peut créer des sous-agents avec leur propre contexte de conversation, prompt système et accès restreint aux outils. Utile pour parler à des personnes extérieures afin d'accomplir des tâches ou d'organiser des choses, tout en gardant un tampon entre la personne extérieure et l'agent principal.
• Auto-programmation. L'agent peut se programmer et s'étendre lui-même.
• Exécution Python en sandbox. Python arbitraire avec dépendances pip via uv, isolé de l'environnement hôte.
• Planification. L'agent peut planifier ses propres tâches récurrentes ou ponctuelles.

Démarrage rapide

Installation assistée par IA : Demandez à votre IA de codage (Claude Code, Cursor, Windsurf, etc.) de récupérer et suivre https://stavrobot.stavros.io/INSTALL.md — elle vous guidera à travers toute la configuration de manière interactive.

Installation manuelle :

1. Envoyez un message à @BotFather sur Telegram pour créer un bot et copiez le token. Envoyez un message à @userinfobot pour obtenir votre ID utilisateur Telegram (utilisé comme chat ID).

2. Copiez env.example vers .env et changez POSTGRES_PASSWORD pour quelque chose de sécurisé et TZ pour votre fuseau horaire.

3. Copiez config.example.toml vers data/main/config.toml et remplissez les champs requis : apiKey, password, publicHostname, [owner].name, [owner].telegram (votre chat ID), et [telegram].botToken. Tout le reste dans le fichier est optionnel.

4. docker compose up --build

C'est tout. Envoyez un message à votre bot sur Telegram et il répondra. Consultez les sections détaillées de configuration ci-dessous pour Signal, WhatsApp, email et autres options.

Configuration

Config

1. Copiez config.example.toml vers data/main/config.toml.
2. Remplissez les clés API et les paramètres. Le fichier d'exemple contient des commentaires expliquant chaque section.
3. Au minimum, définissez authFile (ou apiKey) et publicHostname. Tout le reste est optionnel.
4. Copiez env.example vers .env et définissez votre fuseau horaire (TZ). Les identifiants Postgres et autres paramètres d'environnement peuvent également y être redéfinis. Définissez toujours POSTGRES_PASSWORD sur quelque chose de sécurisé — la valeur par défaut est un placeholder faible et ne doit pas être utilisée en production.

Éditeur de config

Après le démarrage de l'application, ouvrez /settings/config pour modifier config.toml dans le navigateur. La page est protégée par HTTP Basic Auth et affiche la configuration brute, y compris les secrets qu'elle contient. Une sauvegarde valide crée une seule sauvegarde <CONFIG_PATH>.bak, enregistre le nouveau contenu et redémarre l'application ; cela interrompt tout tour d'agent en cours.

plugin-runner, coder, signal-bridge et python-runner ne lisent config.toml qu'à leur démarrage. Les modifications qui les concernent, comme le mot de passe, nécessitent de redémarrer manuellement ces conteneurs.

Points de terminaison personnalisés et compatibles OpenAI

Stavrobot peut être pointé vers n'importe quel point de terminaison compatible OpenAI (Ollama, LiteLLM, vLLM, etc.) ou un proxy personnalisé compatible Anthropic en définissant baseUrl dans config.toml. Consultez config.example.toml pour les champs requis et des exemples de configuration. Définissez reasoning = true uniquement pour les modèles qui prennent en charge la réflexion, car c'est ce qui fait que thinkingLevel s'applique sur un point de terminaison personnalisé.

Authentification

L'application prend en charge deux modes d'authentification : clé API ou OAuth.

• Clé API : Définissez apiKey dans config.toml. Aucune connexion ni déconnexion nécessaire.
• OAuth : Définissez authFile dans config.toml (un chemin où les identifiants seront stockés). La page de connexion fonctionne avec tout fournisseur OAuth pris en charge par Pi.
  • Connexion : Visitez <your-hostname>/login dans un navigateur. Suivez les instructions de la page, et les identifiants sont enregistrés dans le fichier d'authentification. Stavrobot choisit la méthode de connexion headless du fournisseur, vous n'êtes donc jamais redirigé vers un callback localhost inaccessible. Avec Anthropic, après avoir sélectionné Authorize, Anthropic affiche un code, que vous copiez et collez dans la page de connexion Stavrobot. Les fournisseurs avec un flux device-code affichent le code sur la page Stavrobot à la place, et vous le saisissez sur le site du fournisseur. Si l'authentification expire pendant que le bot fonctionne, il vous envoie un message avec l'URL de connexion via votre plateforme de messagerie.
  • Déconnexion : Supprimez le fichier au chemin authFile. Le bot détectera l'absence d'identifiants au prochain message et vous invitera à vous reconnecter.

Configuration de Claude Code

Le conteneur coder est optionnel (nécessaire uniquement pour la fonctionnalité d'auto-programmation). Par défaut, il utilise Claude Code avec authentification par abonnement (OAuth), séparée de la clé API de l'application principale. Pour utiliser un point de terminaison API compatible Anthropic à la place, définissez à la fois [coder].apiKey et [coder].baseUrl dans config.toml ; Claude Code les utilise alors comme ANTHROPIC_API_KEY et ANTHROPIC_BASE_URL. Les apiKey/baseUrl de niveau supérieur ne configurent que le modèle de l'application principale et n'affectent jamais le coder. Définir une seule des deux clés [coder] est une erreur au démarrage.

Les profils Docker Compose sont séparés par des virgules, vous pouvez donc les combiner (par ex. COMPOSE_PROFILES=signal,coder).