skorokithakis/stavrobotUn assistente personale AI incentrato sulla sicurezza.
Stavrobot è un assistente AI personale costruito con il principio di "tutto l'accesso di cui un assistente AI ha bisogno, e niente di più".
Ha tutte le belle funzionalità di un assistente AI, ma si concentra su sandboxing, isolamento e permessi minimi. È leggero e si distribuisce con un semplice docker compose up.
uv, isolato dall'ambiente host.Installazione assistita dall'AI: Dì al tuo coding AI (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:
env.example in .env e cambia POSTGRES_PASSWORD con qualcosa di sicuro e TZ con il tuo fuso orario.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.docker compose up --buildQuesto è tutto. Invia un messaggio al tuo bot su Telegram e risponderà. Vedi le sezioni di configurazione dettagliate qui sotto per Signal, WhatsApp, email e altre opzioni.
config.example.toml in data/main/config.toml.authFile (o apiKey) e publicHostname. Tutto il resto è opzionale.env.example in .env e imposta il tuo fuso orario (TZ). Le credenziali di Postgres e altre impostazioni di ambiente possono essere sovrascritte lì. Imposta sempre POSTGRES_PASSWORD come qualcosa di sicuro — il valore predefinito è un segnaposto debole e non deve essere usato in produzione.Stavrobot può essere puntato a qualsiasi endpoint compatibile con OpenAI (Ollama, LiteLLM, vLLM, ecc.) o a un proxy personalizzato compatibile con Anthropic impostando baseUrl in config.toml. Vedi config.example.toml per i campi richiesti e configurazioni di esempio.
L'app supporta due modalità di autenticazione: chiave API o OAuth.
apiKey in config.toml. Nessun login o logout necessario.authFile in config.toml (un percorso in cui verranno memorizzate le credenziali). La pagina di login funziona con qualsiasi provider OAuth supportato da Pi.
<il-tuo-hostname>/login in un browser. Segui le istruzioni sulla pagina e le credenziali vengono salvate nel file di autenticazione. Se l'autenticazione scade mentre il bot è in esecuzione, ti invia un messaggio con l'URL di login tramite la tua piattaforma di messaggistica.authFile. Il bot rileverà le credenziali mancanti al prossimo messaggio e ti chiederà di effettuare di nuovo il login.Il container coder è opzionale (necessario solo per la funzionalità di autoprogrammazione). Usa Claude Code con autenticazione tramite abbonamento (OAuth), separata dalla chiave API dell'app principale.
I profili di Docker Compose sono separati da virgole, quindi puoi combinarli (ad es. COMPOSE_PROFILES=signal,coder).
COMPOSE_PROFILES nel tuo file .env per includere coder (ad es. COMPOSE_PROFILES=coder, o COMPOSE_PROFILES=signal,coder se stai usando anche Signal).docker compose --profile coder up --builddocker compose exec -u coder coder claude (ti chiederà di fare login se non l'hai ancora fatto).[coder].model nella tua configurazione su un alias di modello Claude Code (sonnet, opus o haiku).Signal richiede un numero di telefono separato — non il tuo personale. Una SIM prepagata o un numero VoIP funzionano.
COMPOSE_PROFILES=signal nel tuo file .env per abilitare il container 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)' — scansiona il codice QR con il tuo telefono (Signal > Impostazioni > Dispositivi collegati).docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +TuoNumero register', poi verifica con docker compose --profile signal run --rm --entrypoint bash signal-bridge -c 'signal-cli -u +TuoNumero verify CODICE'.[signal].account nella tua configurazione.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 nella tua configurazione.[owner].telegram nella tua configurazione./settings.WhatsApp richiede un numero di telefono separato, altrimenti ti invieresti messaggi da solo, il che non funziona.
WhatsApp usa Baileys, una libreria WhatsApp Web non ufficiale che si collega come dispositivo compagno (come WhatsApp Web). Non è necessario un numero di telefono separato — si collega al tuo account WhatsApp esistente.
Rischio: Baileys utilizza un'API non ufficiale. WhatsApp potrebbe bannare gli account che la usano. Usa a tuo rischio.
[whatsapp] al tuo config.toml (vedi config.example.toml per il formato).docker compose up --builddocker compose logs -f app)../data/whatsapp./settings.L'email utilizza un Cloudflare Email Worker per la consegna in entrata e SMTP per l'uscita. Vedi
config.example.toml per il codice worker completo e le istruzioni dettagliate di configurazione.
[email] al tuo config.toml con le credenziali SMTP e un webhookSecret casuale.config.example.toml) e imposta le variabili d'ambiente WEBHOOK_URL e WEBHOOK_SECRET sul worker./settings.docker compose up --build
L'API è disponibile su http://localhost:10567/chat.
Nota: Docker Compose espone l'app solo su localhost:10567. Per renderla accessibile dall'esterno (necessario per webhook Telegram/Signal e l'impostazione publicHostname), configura un reverse proxy (es. Nginx, Caddy) che punti a localhost:10567. Puoi anche esporre direttamente la porta, ma non è raccomandato poiché il traffico non sarà crittografato.
Richiede Node.js >= 20 e un'istanza PostgreSQL in esecuzione.
npm install && npm run build && npm start
Nota: L'esecuzione di Python e l'integrazione con Signal funzionano solo all'interno dei container Docker.
Stavrobot ha un sistema di conoscenza a tre livelli: memorie, un blocco note e il database. Gestirà questi abbastanza bene da solo, ma è importante che tu li conosca perché vorrai aiutare il bot a usarli correttamente.
Le memorie vengono sempre iniettate interamente nel prompt di sistema. Dovresti essere parsimonioso con queste, poiché vengono incluse nel contesto ogni volta, e averne molte può aumentare il contesto. Un esempio di buona memoria potrebbe essere "l'utente preferisce chattare in uno stile informale.", qualcosa che il bot dovrebbe sapere ogni volta, anche se ciò costa in lunghezza aggiuntiva del contesto.
Il blocco note è dove il bot conserva le conoscenze a cui si accede meno frequentemente, ma conoscenze che riguardano un argomento. Le voci del blocco note hanno un titolo e un corpo, e il titolo viene iniettato nel contesto automaticamente. Usalo per cose importanti, ma meno frequentemente necessarie, cose che di solito riguardano un argomento specifico.
Ad esempio, una buona voce del blocco note potrebbe essere "preferenze alimentari", con dettagli su cosa ti piace mangiare, quando, ecc. Il bot vedrà che c'è un argomento "preferenze alimentari", ma non caricherà il testo effettivo nel contesto automaticamente, accedendovi solo su richiesta.
Quando parli con il bot di cibo, saprà che c'è una voce del blocco note "preferenze alimentari" a cui può guardare, e di solito lo farà da solo.
Il database è il terzo livello, per dati strutturati o in blocco che non appartengono a memorie o al blocco note. Il bot ha accesso completo in lettura/scrittura a PostgreSQL tramite SQL senza restrizioni, quindi può creare tabelle, eseguire query e memorizzare qualsiasi cosa. Usalo per cose come elenchi, log, record strutturati o qualsiasi dato che sia meglio interrogato che letto come prosa.
Il bot di solito saprà abbastanza bene cosa usare quando, ma a volte vorrai dirgli esplicitamente quali informazioni mettere dove.
Stavrobot può inviare messaggi per tuo conto tramite Signal, Telegram, WhatsApp o email. Hai bisogno di organizzare una cena con un amico? Dì al bot di trovare un orario che funzioni per entrambi, e invierà loro un messaggio, negozierà una data e la inserirà nel tuo calendario. Vuoi organizzare un appuntamento, coordinare un'uscita di gruppo o chiedere a qualcuno una domanda mentre sei occupato? Basta dire al bot cosa ti serve e con chi parlare.
Il bot avvia un subagente dedicato per ogni conversazione, con le proprie istruzioni e contesto, in modo da poter gestire lo scambio con l'altra persona senza ingombrare la tua chat principale. Quando il compito è terminato, disabilita il contatto e ti riferisce i risultati.
Per mantenere le cose sicure, la messaggistica richiede due cose prima che il bot possa parlare con qualcuno:
/settings e aggiungi il suo numero di telefono
(Signal o WhatsApp) o chat ID (Telegram). Questo è un passaggio una tantum per persona. Il
bot non può modificare questa lista né inviare messaggi a chi non è presente, indipendentemente da ciò che gli viene detto.Un flusso tipico: aggiungi il numero di telefono del tuo amico alla lista consentita tramite /settings una volta,
poi dici al bot "trova un orario per cena con Alex la prossima settimana". Il bot crea un record
di contatto per Alex, avvia un subagente, invia un messaggio ad Alex su Signal, va avanti e indietro
per trovare una data e ti riporta il risultato.
Le abilità sono file di istruzioni in testo semplice che insegnano al bot nuove capacità — cose come creare tabelle, memorizzare conoscenze, creare pagine o seguire flussi di lavoro specifici. Non sono codice; sono istruzioni in linguaggio naturale che il bot legge e segue.
Per installare il sistema di abilità, dì al bot di recuperare
https://stavrobot.stavros.io/skills/bootstrap.md e di seguirne le istruzioni.
Un elenco completo delle abilità disponibili si trova su
https://stavrobot.stavros.io/skills/index.md. Per installare un'abilità, basta dire al bot di
recuperarla e installarla da quell'URL. Il bot ti mostrerà cosa fa l'abilità e chiederà
conferma prima di procedere.
I file delle abilità risiedono nel branch pages di questo repository (servito tramite Cloudflare Pages). Per
contribuire con un'abilità, aggiungi un file Markdown in skills/ su quel branch. Ogni file di abilità ha
intestazione YAML con title, description, version e un author opzionale,
seguito dalle istruzioni in linguaggio semplice nel corpo. Vedi
SKILL-AUTHORING.md per la guida completa alla scrittura. Invia una PR
sul branch pages.
Vedi PLUGIN.md per tutto ciò che devi sapere per creare un plugin per Stavrobot. Lo stesso documento funge da riferimento sia per umani che per LLM.
I plugin sono abbastanza necessari per abilitare funzionalità core del bot, come la capacità di "sentire" note vocali, inviare note vocali di ritorno, essere consapevole dei luoghi intorno a te, cercare sul web, ecc.
Queste capacità non sono fornite pronte all'uso per darti la possibilità di personalizzare il tuo bot come preferisci. Dovresti comunque installare plugin, altrimenti ti mancheranno funzionalità cruciali.
Puoi trovare alcuni plugin di prima parte qui:
Tre container Docker core: app (server TypeScript, espone POST /chat, gestisce webhook Telegram su POST /telegram/webhook, gestisce webhook email in entrata su POST /email/webhook ed esegue WhatsApp in-process tramite Baileys), postgres (PostgreSQL 17 per lo stato persistente) e plugin-runner (server Node.js — elenca, ispeziona ed esegue plugin, sia creati localmente che installati tramite git). Un container opzionale coder (agente headless di Claude Code per creare e modificare plugin modificabili) è abilitato tramite il profilo Docker Compose coder. L'agente principale può creare subagenti, ciascuno con la propria cronologia di conversazione, prompt di sistema e whitelist di strumenti. Gli interlocutori sono record di contatto assegnati agli agenti per il routing dei messaggi in arrivo.