Questo articolo presenta l’architettura e l’implementazione di un assistente AI home server che permette l’interazione in linguaggio naturale con la tua infrastruttura Raspberry Pi. La soluzione utilizza n8n come layer di orchestrazione, OpenRouter (modello DeepSeek) per le capacità LLM, e Telegram come interfaccia utente, con un approccio security-first.
Definizione del Problema
La gestione di un’infrastruttura home server con molteplici progetti Docker richiede frequente accesso SSH per monitoraggio, analisi log e troubleshooting. Gli approcci tradizionali comportano l’apertura di sessioni terminale, ricordare la sintassi dei comandi e navigare strutture di directory. Questo crea attrito, specialmente quando sono necessari controlli rapidi da dispositivi mobili.
L’assistente AI home server doveva soddisfare diversi requisiti:
- Interfaccia in linguaggio naturale accessibile da qualsiasi dispositivo
- Esecuzione sicura dei comandi con molteplici livelli di validazione
- Integrazione con Claude CLI per analisi intelligente del codice
- Memoria conversazionale per interazioni contestuali
- Protezione contro operazioni pericolose
Architettura dell’Assistente AI Home Server
L’assistente AI home server implementa un modello di sicurezza defense-in-depth con sei stadi di elaborazione distinti:
┌─────────────────┐ ┌──────────────┐ ┌─────────────┐
│ Telegram Trigger│────▶│ Filtro User │────▶│ AI Agent │
│ (Webhook) │ │ (Auth Gate) │ │ (DeepSeek) │
└─────────────────┘ └──────────────┘ └──────┬──────┘
│
┌───────────────────────────┘
▼
┌─────────────────┐
│ Command Router │
│ (Regex Match) │
└────────┬────────┘
│
┌─────────────┴─────────────┐
▼ ▼
┌─────────────────┐ ┌─────────────────┐
│ Input Guard │ │ Text Response │
│ (Blocklist) │ │ (Direct Send) │
└────────┬────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐
│ SSH Execute │────▶│ Output Guard │────▶│ Telegram │
│ (Raspberry Pi) │ │ (PII Sanitize) │ │ Send │
└─────────────────┘ └─────────────────┘ └─────────────┘Dettaglio dei Componenti
| Stadio | Componente | Scopo |
|---|---|---|
| 1. Entry | Telegram Trigger | Ricevitore webhook per messaggi in arrivo |
| 2. Auth | Filtro OnlyME | Validazione ID utente (singolo utente autorizzato) |
| 3. NLU | AI Agent + DeepSeek | Comprensione linguaggio naturale e generazione comandi |
| 4. Routing | IsCommand | Classificazione regex: comando vs conversazione |
| 5. Sicurezza | InputGuard | Blocklist comandi pericolosi |
| 6. Esecuzione | Nodo SSH | Esecuzione sicura comandi su host target |
| 7. Sanitizzazione | OutputGuard | Rimozione PII dall’output comandi |
| 8. Risposta | Telegram Send | Consegna risposta formattata |
Stack Tecnologico
Configurazione LLM
L’AI Agent utilizza OpenRouter come gateway LLM, configurato specificamente con il modello deepseek/deepseek-chat. Questa scelta fornisce:
- Inferenza cost-effective per l’interpretazione comandi
- Forti capacità di seguire istruzioni
- Supporto affidabile per tool-calling
- Risposte a bassa latenza adatte all’uso interattivo
Gestione della Memoria
Il workflow implementa una Buffer Window Memory con una finestra di contesto di 10 messaggi. L’isolamento delle sessioni è ottenuto usando come chiave il chat ID di Telegram, garantendo che il contesto conversazionale persista tra le interazioni rimanendo specifico per utente.
Implementazione della Sicurezza
Layer 1: Autenticazione Utente
Il primo layer di sicurezza valida l’ID utente Telegram contro una whitelist autorizzata. Solo i messaggi dall’ID utente configurato procedono all’AI agent. Tutti gli altri messaggi vengono scartati silenziosamente.
Layer 2: Classificazione Comandi
Un router basato su regex determina se l’output dell’AI rappresenta un comando eseguibile o una risposta testuale:
^(docker|cd |df |free |top |uptime|cat |ls |grep |tail |head |ps |/home/user|sudo )Layer 3: Guardrails Input
Il nodo InputGuard implementa una blocklist completa per operazioni pericolose:
| Categoria | Pattern Bloccati |
|---|---|
| Distruttivi | rm -rf, rm -r /, shred |
| Controllo Sistema | shutdown, reboot, poweroff, halt |
| Operazioni Disco | mkfs, dd if=, >/dev/sd |
| Escalation Permessi | passwd, chmod 777, chown -R root |
| Esecuzione Remota | wget\|bash, curl\|sh, base64 -d\|bash |
| Reverse Shell | nc -e, netcat -e |
| Fork Bomb | :(){ :\|:& }; |
Layer 4: Sanitizzazione Output
Il nodo OutputGuard applica sanitizzazione PII a tutti gli output dei comandi prima della trasmissione. Questo previene l’esposizione accidentale di chiavi API, password, chiavi private e informazioni personali identificabili.
Integrazione Claude CLI
Una delle funzionalità più potenti è l’integrazione con Claude Code CLI. Quando gli utenti richiedono analisi del codice o spiegazioni di progetti, l’AI genera comandi che invocano Claude CLI nella directory appropriata:
cd /home/user/docker-compose-files/ai_trading && \
/home/user/.local/bin/claude -p "check for errors in logs and code"Questo abilita operazioni sofisticate come analisi errori, spiegazione codice, parsing log e audit delle dipendenze.
Conclusione
Questo assistente AI home server dimostra come gli strumenti moderni di orchestrazione AI possono creare interfacce potenti e sicure per la gestione dell’infrastruttura. L’approccio defense-in-depth assicura che anche con la flessibilità del linguaggio naturale, i confini di sicurezza rimangano robusti.
Approfondimenti
Questo articolo è stato scritto con Claude Code CLI di Anthropic.