PiSovereign Documentation
A self-hosted, privacy-first AI assistant platform — deploy anywhere with Docker Compose.
Welcome to the official PiSovereign documentation. This guide covers everything from first deployment to production operations and development.
Introduction
PiSovereign runs a complete AI assistant stack on your own hardware. All inference stays local via Ollama — no data ever leaves your network. It deploys as a set of Docker containers on any Linux or macOS host and is optimized for the Raspberry Pi 5 with Hailo-10H NPU.
Core Principles:
- Privacy First — All processing happens locally on your hardware
- GDPR Compliant — No data leaves your network
- Open Source — MIT licensed, fully auditable,
#![forbid(unsafe_code)] - Extensible — Clean Architecture with Ports & Adapters
Key Features
| Feature | Description |
|---|---|
| Local LLM Inference | Ollama with dynamic model routing by task complexity |
| Signal & WhatsApp | Bidirectional messaging with voice message support |
| Voice Processing | Local STT (whisper.cpp) and TTS (Piper), optional OpenAI fallback |
| Calendar & Contacts | CalDAV/CardDAV (Baïkal, Radicale, Nextcloud) |
| IMAP/SMTP with any provider (Gmail, Outlook, Proton Mail) | |
| Weather & Transit | Open-Meteo forecasts, German public transit via HAFAS |
| Web Search | Brave Search with automatic DuckDuckGo fallback |
| Persistent Memory | RAG with embeddings, decay, deduplication, XChaCha20 encryption |
| Reminders | Natural language scheduling with morning briefings |
| Agentic Mode | Multi-agent orchestration for complex tasks with parallel sub-agents |
| Secret Management | HashiCorp Vault with AppRole authentication |
| Observability | Prometheus, Grafana, Loki, OpenTelemetry |
| Docker Compose | Single-command deployment with optional monitoring and CalDAV profiles |
Quick Links
User Guide
| Document | Description |
|---|---|
| Getting Started | 5-minute Docker deployment |
| Hardware Setup | Raspberry Pi 5 + Hailo-10H assembly |
| Docker Setup | Detailed deployment and operations guide |
| Vault Setup | Secret management with HashiCorp Vault |
| Configuration | All config.toml options |
| External Services | WhatsApp, email, CalDAV, search setup |
| Signal Setup | Signal messenger registration |
| Reminder System | Reminders and morning briefings |
| Troubleshooting | Common issues and solutions |
Developer Guide
| Document | Description |
|---|---|
| Architecture | Clean Architecture overview |
| Memory System | RAG pipeline and encryption |
| Contributing | Development setup and workflow |
| Crate Reference | All 16 workspace crates documented |
| API Reference | REST API with OpenAPI spec |
Operations & Security
| Document | Description |
|---|---|
| Production Deployment | TLS, production config, multi-arch builds |
| Monitoring | Prometheus, Grafana, Loki, alerting |
| Backup & Restore | Data protection and recovery |
| Security Hardening | Application, network, and Vault security |
Getting Help
- GitHub Issues: Report bugs or request features
- Discussions: Ask questions and share ideas
- Security Issues: Report vulnerabilities privately via GitHub Security Advisories