skorokithakis/stavrobotEin KI-gestützter persönlicher Assistent mit Schwerpunkt auf Sicherheit.
Stavrobot ist ein persönlicher KI-Assistent, der nach dem Prinzip „so viel Zugriff, wie ein KI-Assistent benötigt, und nicht mehr“ aufgebaut ist.
Er bietet alle nützlichen Funktionen eines KI-Assistenten, konzentriert sich jedoch auf Sandboxing, Isolierung und minimale Berechtigungen. Er ist leichtgewichtig und wird mit nur einem docker compose up bereitgestellt.
uv, isoliert von der Host-Umgebung.KI-gestützte Installation: Sagen Sie Ihrer Code-KI (Claude Code, Cursor, Windsurf usw.), sie solle https://stavrobot.stavros.io/INSTALL.md abrufen und befolgen – sie führt Sie interaktiv durch die gesamte Einrichtung.
Manuelle Installation:
Schreiben Sie @BotFather auf Telegram, um einen Bot zu erstellen, und kopieren Sie den Token. Schreiben Sie @userinfobot, um Ihre Telegram-Benutzer-ID zu erhalten (diese wird als Chat-ID verwendet).
Kopieren Sie env.example nach .env und ändern Sie POSTGRES_PASSWORD in etwas Sicheres und TZ in Ihre Zeitzone.
Kopieren Sie config.example.toml nach data/main/config.toml und füllen Sie die erforderlichen Felder aus: apiKey, password, publicHostname, [owner].name, [owner].telegram (Ihre Chat-ID) und [telegram].botToken. Alles andere in der Datei ist optional.
docker compose up --build
Das war's. Schreiben Sie Ihrem Bot auf Telegram, und er wird antworten. Die detaillierten Einrichtungsabschnitte für Signal, WhatsApp, E-Mail und andere Optionen finden Sie weiter unten.
config.example.toml nach data/main/config.toml.authFile (oder apiKey) und publicHostname gesetzt werden. Alles andere ist optional.env.example nach .env und setzen Sie Ihre Zeitzone (TZ). Postgres-Anmeldedaten und andere Umgebungseinstellungen können dort ebenfalls überschrieben werden. Setzen Sie POSTGRES_PASSWORD immer auf etwas Sicheres – der Standardwert ist ein schwacher Platzhalter und sollte nicht in der Produktion verwendet werden.Stavrobot kann auf jeden OpenAI-kompatiblen Endpunkt (Ollama, LiteLLM, vLLM usw.) oder einen benutzerdefinierten Anthropic-kompatiblen Proxy ausgerichtet werden, indem baseUrl in config.toml gesetzt wird. Siehe config.example.toml für die erforderlichen Felder und Beispielkonfigurationen.
Die App unterstützt zwei Authentifizierungsmodi: API-Schlüssel oder OAuth.
apiKey in config.toml. Kein Login oder Logout erforderlich.authFile in config.toml (ein Pfad, in dem Anmeldeinformationen gespeichert werden). Die Login-Seite funktioniert mit jedem OAuth-Anbieter, der von Pi unterstützt wird.
<your-hostname>/login in einem Browser. Folgen Sie den Anweisungen auf der Seite, und die Anmeldeinformationen werden in der Auth-Datei gespeichert. Wenn die Authentifizierung während des Bot-Betriebs abläuft, sendet er Ihnen über Ihre Messaging-Plattform eine Nachricht mit der Login-URL.authFile-Pfad. Der Bot erkennt fehlende Anmeldeinformationen bei der nächsten Nachricht und fordert Sie auf, sich erneut anzumelden.Der coder-Container ist optional (wird nur für die Selbstprogrammierungsfunktion benötigt). Er verwendet Claude Code mit Abonnement-Auth (OAuth), getrennt vom API-Schlüssel der Haupt-App.
Docker Compose-Profile werden kommagetrennt, sodass Sie sie kombinieren können (z. B. COMPOSE_PROFILES=signal,coder).
COMPOSE_PROFILES in Ihrer .env-Datei so, dass es coder enthält (z. B. COMPOSE_PROFILES=coder oder COMPOSE_PROFILES=signal,coder, wenn Sie auch Signal verwenden).docker compose --profile coder up --builddocker compose exec -u coder coder claude (es wird zur Anmeldung aufgefordert, falls noch nicht geschehen).[coder].model in Ihrer Konfiguration auf einen Claude Code-Modell-Alias (sonnet, opus oder haiku).Signal erfordert eine separate Telefonnummer – nicht Ihre persönliche. Eine Prepaid-SIM oder VoIP-Nummer funktioniert.
COMPOSE_PROFILES=signal in Ihrer .env-Datei, um den signal-bridge-Container zu aktivieren.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)' – scannen Sie den QR-Code mit Ihrem Telefon (Signal > Einstellungen > Verknüpfte Geräte).docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +YOUR_NUMBER register', dann verifizieren mit docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +YOUR_NUMBER verify CODE'.[signal].account in Ihrer Konfiguration.docker compose up --build/settings-Weboberflache hinzu.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 in Ihrer Konfiguration.[owner].telegram in Ihrer Konfiguration./settings-Weboberflache hinzu.WhatsApp erfordert eine separate Telefonnummer, da Sie sich sonst selbst schreiben würden, was nicht wirklich funktioniert.
WhatsApp verwendet Baileys, eine inoffizielle WhatsApp-Web-Bibliothek, die sich als Begleitgerät verbindet (wie WhatsApp Web). Es ist keine separate Telefonnummer erforderlich – sie verknüpft sich mit Ihrem bestehenden WhatsApp-Konto.
Risiko: Baileys verwendet eine inoffizielle API. WhatsApp kann Konten sperren, die es verwenden. Nutzung auf eigene Gefahr.
[whatsapp]-Abschnitt zu Ihrer config.toml hinzu (siehe config.example.toml für das Format).docker compose up --builddocker compose logs -f app)../data/whatsapp erhalten./settings-Weboberflache hinzu.E-Mail verwendet einen Cloudflare E-Mail-Worker für den eingehenden Versand und SMTP für den ausgehenden. Siehe
config.example.toml für den vollständigen Worker-Code und detaillierte Einrichtungsanweisungen.
[email]-Abschnitt zu Ihrer config.toml mit SMTP-Anmeldedaten und einem zufälligen webhookSecret hinzu.config.example.toml) und setzen Sie die Umgebungsvariablen WEBHOOK_URL und WEBHOOK_SECRET im Worker./settings-Weboberflache hinzu.docker compose up --build
Die API ist verfügbar unter http://localhost:10567/chat.
Hinweis: Docker Compose macht die App nur unter localhost:10567 verfügbar. Um sie extern erreichbar zu machen (erforderlich für Telegram/Signal-Webhooks und die publicHostname-Einstellung), richten Sie einen Reverse-Proxy (z. B. Nginx, Caddy) ein, der auf localhost:10567 zeigt. Sie können den Port auch direkt freigeben, dies wird jedoch nicht empfohlen, da der Datenverkehr dann unverschlüsselt ist.
Erfordert Node.js >= 20 und eine laufende PostgreSQL-Instanz.
npm install && npm run build && npm start
Hinweis: Python-Ausführung und Signal-Integration funktionieren nur innerhalb der Docker-Container.
Stavrobot verfügt über ein dreistufiges Wissenssystem: Erinnerungen, einen Notizblock und die Datenbank. Es wird diese weitgehend selbstständig verwalten, aber es ist wichtig, dass Sie darüber Bescheid wissen, da Sie dem Bot helfen werden, sie richtig zu nutzen.
Erinnerungen werden immer vollständig in den Systemprompt eingefügt. Sie sollten sparsam damit umgehen, da sie jedes Mal in den Kontext aufgenommen werden. Eine große Anzahl von ihnen kann den Kontext vergrößern. Ein Beispiel für eine gute Erinnerung wäre „Der Benutzer bevorzugt einen lockeren Gesprächsstil.“ – etwas, das der Bot jedes Mal wissen sollte, selbst wenn dies zusätzliche Kontextlänge kostet.
Der Notizblock ist der Ort, an dem der Bot weniger häufig benötigtes Wissen speichert, aber Wissen, das sich auf ein Thema bezieht. Notizblockeinträge haben einen Titel und einen Text, und der Titel wird automatisch in den Kontext injiziert. Verwenden Sie dies für wichtige, aber weniger häufig benötigte Dinge, die sich normalerweise auf ein bestimmtes Thema beziehen.
Ein guter Notizblockeintrag wäre zum Beispiel „Ernährungsvorlieben“ mit Details darüber, was Sie gerne essen, wann usw. Der Bot sieht, dass es ein Thema „Ernährungsvorlieben“ gibt, lädt aber den eigentlichen Text nicht automatisch in den Kontext, sondern greift nur bei Bedarf darauf zu.
Wenn Sie mit dem Bot über Essen sprechen, weiß er, dass es einen Notizblockeintrag „Ernährungsvorlieben“ gibt, den er ansehen kann, und er macht das normalerweise von selbst.
Die Datenbank ist die dritte Ebene für strukturierte oder größere Datenmengen, die nicht in Erinnerungen oder den Notizblock gehören. Der Bot hat über uneingeschränktes SQL vollen Lese-/Schreibzugriff auf PostgreSQL, sodass er Tabellen erstellen, Abfragen ausführen und alles speichern kann. Verwenden Sie dies für Dinge wie Listen, Protokolle, strukturierte Aufzeichnungen oder alle Daten, die sich besser abfragen als als Text lesen lassen.
Der Bot wird normalerweise gut genug wissen, was wann zu verwenden ist, aber manchmal möchten Sie ihm explizit sagen, welche Informationen wo abgelegt werden sollen.
Stavrobot kann in Ihrem Namen Personen über Signal, Telegram, WhatsApp oder E-Mail Nachrichten senden. Müssen Sie ein Abendessen mit einem Freund planen? Sagen Sie dem Bot, er soll einen Zeitpunkt finden, der für Sie beide passt, und er wird ihn anschreiben, einen Termin aushandeln und in Ihren Kalender eintragen. Einen Termin vereinbaren, einen Gruppenausflug koordinieren oder jemanden etwas fragen, während Sie beschäftigt sind? Sagen Sie dem Bot einfach, was Sie brauchen und mit wem Sie sprechen möchten.
Der Bot startet für jedes Gespräch einen dedizierten Sub-Agenten mit eigenen Anweisungen und Kontext, sodass er den Hin und Her mit der anderen Person führen kann, ohne Ihren Hauptchat zu überladen. Wenn die Aufgabe erledigt ist, deaktiviert er den Kontakt und berichtet Ihnen.
Aus Sicherheitsgründen sind für die Kommunikation zwei Dinge erforderlich, bevor der Bot mit jemandem sprechen kann:
/settings und fügen Sie ihre Telefonnummer
(Signal oder WhatsApp) oder Chat-ID (Telegram) hinzu. Dies ist ein einmaliger Schritt pro Person. Der
Bot kann diese Liste nicht ändern oder jemanden anschreiben, der nicht darauf steht, egal was passiert.Ein typischer Ablauf: Sie fügen die Telefonnummer Ihres Freundes einmalig über /settings zur Whitelist hinzu,
dann sagen Sie dem Bot: „Finde einen Zeitpunkt fürs Abendessen mit Alex nächste Woche.“ Der Bot erstellt einen Kontakteintrag
für Alex, startet einen Sub-Agenten, schreibt Alex über Signal, spricht hin und her, um ein Datum zu finden,
und meldet Ihnen das Ergebnis.
Fähigkeiten sind Klartext-Anweisungsdateien, die dem Bot neue Fähigkeiten beibringen – Dinge wie das Erstellen von Tabellen, Speichern von Wissen, Erstellen von Seiten oder Befolgen bestimmter Arbeitsabläufe. Sie sind kein Code; es sind natürlichsprachliche Anweisungen, die der Bot liest und befolgt.
Um das Fähigkeitssystem zu installieren, sagen Sie dem Bot, er solle
https://stavrobot.stavros.io/skills/bootstrap.md abrufen und seinen Anweisungen folgen.
Eine vollständige Liste der verfügbaren Fähigkeiten finden Sie unter
https://stavrobot.stavros.io/skills/index.md. Um eine Fähigkeit zu installieren, sagen Sie dem Bot einfach, er solle
sie von dieser URL abrufen und installieren. Der Bot zeigt Ihnen, was die Fähigkeit tut, und bittet um Bestätigung,
bevor er fortfährt.
Die Fähigkeitsdateien liegen im pages-Branch dieses Repos (ausgeliefert über Cloudflare Pages). Um
eine Fähigkeit beizutragen, fügen Sie eine Markdown-Datei zu skills/ in diesem Branch hinzu. Jede Fähigkeitsdatei hat
YAML-Frontmatter mit title, description, version und einem optionalen author,
gefolgt von den Anweisungen in Klartext. Siehe
SKILL-AUTHORING.md für die vollständige Autorenanleitung. Reichen Sie einen PR
gegen den pages-Branch ein.
Siehe PLUGIN.md für alles, was Sie wissen müssen, um ein Stavrobot-Plugin zu erstellen. Dasselbe Dokument dient sowohl Menschen als auch LLMs als Referenz.
Plugins sind ziemlich notwendig, um Kernfunktionen des Bots zu aktivieren, wie die Fähigkeit, Sprachnotizen zu „hören“, Sprachnotizen zurückzusenden, sich über Orte in Ihrer Umgebung bewusst zu sein, das Web zu durchsuchen usw.
Diese Fähigkeiten werden nicht standardmäßig bereitgestellt, damit Sie die Möglichkeit haben, Ihren Bot beliebig anzupassen. Sie sollten jedoch Plugins installieren, da Ihnen sonst wichtige Funktionalitäten fehlen.
Einige Erstanbieter-Plugins finden Sie hier:
Drei zentrale Docker-Container: app (TypeScript-Server, bietet POST /chat, verarbeitet Telegram-Webhooks unter POST /telegram/webhook, verarbeitet eingehende E-Mail-Webhooks unter POST /email/webhook und führt WhatsApp im Prozess über Baileys aus), postgres (PostgreSQL 17 für persistenten Zustand) und plugin-runner (Node.js-Server – listet, inspiziert und führt Plugins aus, sowohl lokal erstellte als auch über Git installierte). Ein optionaler coder-Container (Claude Code Headless-Agent zum Erstellen und Ändern von editierbaren Plugins) wird über das coder-Docker-Compose-Profil aktiviert. Der Haupt-Agent kann Sub-Agenten erstellen, jeder mit eigener Gesprächshistorie, System-Prompt und Tool-Whitelist. Gesprächspartner sind Kontakteinträge, die Agenten für die eingehende Nachrichtenweiterleitung zugewiesen werden.