Stavrobot

Stavrobot è un assistente AI personale costruito secondo il principio di "tutti gli accessi di cui un assistente AI ha bisogno, e non di più".

Ha tutte le belle funzionalità di un assistente AI, ma si concentra su sandboxing, isolamento e permessi minimi. È leggero e viene distribuito con un semplice docker compose up.

Funzionalità

• Sicuro. Tutto viene eseguito in un container, il tuo sistema operativo host è completamente invisibile all'AI. L'AI non vede alcun segreto a meno che tu non voglia.
• Leggero. Non esegue un container per componente. I plugin vengono tutti eseguiti in un singolo container, separati dai permessi Unix.
• Usa qualsiasi modello tu voglia. Locale, OpenRouter, Anthropic/OpenAI. Qualsiasi cosa supporti Pi, il bot può usarla.
• Integrazione Signal/Telegram/WhatsApp/Email. Messaggistica bidirezionale, con formattazione, allegati, ecc.
• Integrazione Pebble Index. Le registrazioni dell'anello possono essere accodate direttamente per l'agente.
• Conoscenza a tre livelli. Ricorda tutto senza saturare il suo contesto. Recupera i dati dalla sua memoria in modo intelligente e trasparente.
• Basso utilizzo di token. Sono state apportate varie ottimizzazioni per essere leggero nell'utilizzo dei token. Usa persino TOON internamente.
• Plugin. Installa plugin ed estendi le capacità di Stavrobot semplicemente fornendogli l'URL di un repository git. I plugin sono isolati tra loro — ciascuno viene eseguito come utente di sistema dedicato senza accesso ai file o alla configurazione degli altri plugin.
• Subagenti. L'agente principale può creare subagenti con il proprio contesto di conversazione, prompt di sistema e accesso limitato agli strumenti. Utile per parlare con persone esterne per completare attività o organizzare cose, mantenendo un buffer tra la persona esterna e l'agente principale.
• Auto-programmazione. L'agente può programmare ed estendere se stesso.
• Esecuzione Python in sandbox. Python arbitrario con dipendenze pip tramite uv, isolato dall'ambiente host.
• Pianificazione. L'agente può pianificare le proprie attività ricorrenti o una tantum.

Avvio rapido

Installazione assistita dall'AI: Di' alla tua AI di programmazione (Claude Code, Cursor, Windsurf, ecc.) di recuperare e seguire https://stavrobot.stavros.io/INSTALL.md — ti guiderà attraverso l'intera configurazione in modo interattivo.

Installazione manuale:

1. Invia un messaggio a @BotFather su Telegram per creare un bot e copia il token. Invia un messaggio a @userinfobot per ottenere il tuo ID utente Telegram (viene usato come chat ID).

2. Copia env.example in .env e cambia POSTGRES_PASSWORD con qualcosa di sicuro e TZ con il tuo fuso orario.

3. Copia config.example.toml in data/main/config.toml e compila i campi obbligatori: apiKey, password, publicHostname, [owner].name, [owner].telegram (il tuo chat ID) e [telegram].botToken. Tutto il resto nel file è opzionale.

4. docker compose up --build

Fatto. Invia un messaggio al tuo bot su Telegram e risponderà. Consulta le sezioni dettagliate sulla configurazione qui sotto per Signal, WhatsApp, email e altre opzioni.

Configurazione

Config

1. Copia config.example.toml in data/main/config.toml.
2. Compila le chiavi API e le impostazioni. Il file di esempio contiene commenti che spiegano ogni sezione.
3. Come minimo, imposta authFile (o apiKey) e publicHostname. Tutto il resto è opzionale.
4. Copia env.example in .env e imposta il tuo fuso orario (TZ). Anche le credenziali Postgres e altre impostazioni d'ambiente possono essere sovrascritte lì. Imposta sempre POSTGRES_PASSWORD con qualcosa di sicuro — il valore predefinito è un segnaposto debole e non dovrebbe essere usato in produzione.

Editor della config

Dopo l'avvio dell'app, apri /settings/config per modificare config.toml nel browser. La pagina è protetta da HTTP Basic Auth e mostra la configurazione grezza, inclusi eventuali segreti che contiene. Un salvataggio valido crea un singolo backup <CONFIG_PATH>.bak, salva il nuovo contenuto e riavvia l'app; questo interrompe qualsiasi turno dell'agente in corso.

plugin-runner, coder, signal-bridge e python-runner leggono config.toml solo all'avvio. Le modifiche che li riguardano, come la password, richiedono il riavvio manuale di quei container.

Endpoint personalizzati e compatibili con OpenAI

Stavrobot può essere puntato verso qualsiasi endpoint compatibile con OpenAI (Ollama, LiteLLM, vLLM, ecc.) o un proxy personalizzato compatibile con Anthropic impostando baseUrl in config.toml. Consulta config.example.toml per i campi obbligatori e le configurazioni di esempio. Imposta reasoning = true solo per i modelli che supportano il thinking, poiché è ciò che fa applicare thinkingLevel su un endpoint personalizzato.

Autenticazione

L'app supporta due modalità di autenticazione: chiave API o OAuth.

• Chiave API: Imposta apiKey in config.toml. Non è necessario login o logout.
• OAuth: Imposta authFile in config.toml (un percorso in cui verranno memorizzate le credenziali). La pagina di login funziona con qualsiasi provider OAuth supportato da Pi.
  • Login: Visita <your-hostname>/login in un browser. Segui le istruzioni sulla pagina e le credenziali vengono salvate nel file di autenticazione. Stavrobot sceglie il metodo di login headless del provider, quindi non vieni mai reindirizzato a un callback localhost irraggiungibile. Con Anthropic, dopo aver selezionato Authorize, Anthropic mostra un codice, che copi e incolli nella pagina di login di Stavrobot. I provider con un flusso device-code mostrano invece il codice sulla pagina di Stavrobot, e tu lo digiti sul sito del provider. Se l'autenticazione scade mentre il bot è in esecuzione, invia un messaggio con l'URL di login tramite la tua piattaforma di messaggistica.
  • Logout: Elimina il file nel percorso authFile. Il bot rileverà le credenziali mancanti al messaggio successivo e ti chiederà di effettuare nuovamente il login.

Configurazione di Claude Code

Il container coder è opzionale (necessario solo per la funzionalità di auto-programmazione). Per impostazione predefinita usa Claude Code con autenticazione tramite abbonamento (OAuth), separata dalla chiave API dell'app principale. Per usare invece un endpoint API compatibile con Anthropic, imposta sia [coder].apiKey che [coder].baseUrl in config.toml; Claude Code li userà quindi come ANTHROPIC_API_KEY e ANTHROPIC_BASE_URL. I apiKey/baseUrl di livello superiore configurano solo il modello dell'app principale e non influenzano mai il coder. Impostare solo una delle due chiavi [coder] è un errore di avvio.

I profili di Docker Compose sono separati da virgole, quindi puoi combinarli (ad es. COMPOSE_PROFILES=signal,coder).

1. Imposta COMPOSE_PROFILES nel tuo file .env per includere coder (ad es. COMPOSE_PROFILES=coder, oppure COMPOSE_PROFILES=signal,coder se stai usando anche Signal).
2. Avvia i container: docker compose --profile coder up --build
3. Effettua il login (salta questo e il prossimo passaggio se hai impostato [coder].apiKey/[coder].baseUrl): docker compose exec -u coder coder claude (ti chiederà di effettuare il login se non l'hai fatto).
4. Segui il flusso OAuth basato su browser.
5. Imposta [coder].model nella tua config con un alias di modello Claude Code (sonnet, opus o haiku).

Configurazione di Signal

Signal richiede un numero di telefono separato — non quello personale. Va bene una SIM prepagata o un numero VoIP.