Content
# 🏛️ Odysee – Selbstgehostetes KI-Interface für macOS
[](https://www.apple.com/macos/)
[](https://www.python.org/)
[](https://fastapi.tiangolo.com/)
[](https://www.docker.com/)
[](LICENSE)
**Odysee** (ehemals Odysseus) ist ein vollständig selbstgehostetes, lokales KI-Interface für deinen Mac.
Chatte mit lokalen Modellen (LM Studio, Ollama), Cloud-Providern (DeepSeek, SiliconFlow, Anthropic), verwalte Dokumente, E-Mails, Termine und nutze KI-Assistenten – alles lokal, alles unter deiner Kontrolle.
> **Clean Build** – Dieses Repository enthält einen vollständig bereinigten Build ohne persönliche Konfiguration, API-Keys oder MCP-Server-Verknüpfungen. Ideal zum Forken, Weiterentwickeln oder als Grundlage für eigene Projekte.
---
## ✨ Features
- **💬 Multi-Provider Chat** – LM Studio, Ollama, OpenAI, DeepSeek, SiliconFlow, Anthropic & mehr
- **🤖 KI-Assistenten** – Eigene Assistenten mit individuellen System-Prompts erstellen
- **📄 Dokumenten-Management** – PDFs, Office-Dateien & Markdown mit RAG-Suche
- **📧 E-Mail-Client** – Integrierter IMAP/SMTP-Client mit KI-Triage
- **📅 Kalender** – CalDAV-Sync mit Terminverwaltung
- **🧠 RAG & Semantic Search** – Volltext + Vektor-Suche über deine Dokumente
- **🍳 Cookbook** – Eigene Modelle herunterladen und als lokale API bereitstellen
- **🔧 MCP-Server** – Eigene Tools und Erweiterungen via MCP-Protokoll
- **🔬 Deep Research** – Mehrstufige Recherche mit Quellenanalyse
- **📞 Kontakte** – VCF-Import und -Verwaltung
- **🎨 Bildergalerie** – Mit KI-Bildanalyse
- **🔐 Lokale Authentifizierung** – Kein Cloud-Zwang, alles auf deinem Rechner
- **📝 Notizen & Aufgaben** – Mit Erinnerungen und KI-gestützter Aufgabenverwaltung
---
## 📦 Systemvoraussetzungen
| Komponente | Mindestens | Empfohlen |
|-----------|-----------|-----------|
| **Betriebssystem** | macOS 11 (Big Sur) | macOS 14+ (Sonoma/Sequoia) |
| **Prozessor** | Apple Silicon (M1) | Apple Silicon (M2+) |
| **RAM** | 8 GB | 16 GB+ |
| **Speicher** | 500 MB frei | 2 GB+ (für Modelle & Cache) |
| **Python** | 3.11 | 3.11 |
---
## 🚀 Installation
### 1. Repository klonen
```bash
git clone https://github.com/AlexDesign420/Odysee-MacOS-App.git
cd Odysee-MacOS-App
```
### 2. Virtuelle Umgebung einrichten
```bash
python3.11 -m venv venv
source venv/bin/activate
```
### 3. Abhängigkeiten installieren
```bash
pip install -r requirements.txt
python setup.py
```
### 4. Konfiguration anpassen
```bash
cp .env.example .env
# Standardwerte funktionieren out-of-the-box
```
### 5. Starten
```bash
./venv/bin/uvicorn app:app --host 127.0.0.1 --port 7860
```
Oder per Skript:
```bash
./start-clean.sh
```
**Im Browser öffnen:** http://127.0.0.1:7860
Beim ersten Start wird ein Admin-Zugang erstellt – die Zugangsdaten erscheinen im Terminal.
---
## ⚙️ LLM-Provider verbinden
| Provider | Verbindung | Konfiguration |
|----------|-----------|---------------|
| **LM Studio** | Automatisch via Port 1234 | LM Studio Server starten (Port 1234) |
| **Ollama** | Automatisch via Port 11434 | `OLLAMA_BASE_URL=http://localhost:11434/v1` |
| **DeepSeek** | API-Key erforderlich | In Settings → Provider eintragen |
| **SiliconFlow** | API-Key erforderlich | In Settings → Provider eintragen |
| **OpenAI** | API-Key erforderlich | In Settings → Provider eintragen |
| **Anthropic** | API-Key erforderlich | In Settings → Provider eintragen |
---
## 🐳 Docker (optional)
```bash
docker compose up -d
```
Für NVIDIA-GPU:
```bash
COMPOSE_FILE=docker-compose.yml:docker/gpu.nvidia.yml docker compose up -d
```
Öffne http://localhost:7000.
---
## 🏗️ Eigenen Launcher bauen
Die macOS-App (.app) und DMG bauen:
```bash
./build-macos-app.sh
```
**Ausgabe:**
- `dist/Odysseus.app` – Doppelklick-Start (Shell-Launcher, kein Binary)
- `dist/Odysseus.dmg` – Installations-Disk-Image
> Der Launcher startet den Python-Webserver und öffnet die UI in einem chromeless Fenster (via pywebview oder Chromium).
---
## 🧪 Tests ausführen
```bash
source venv/bin/activate
pytest tests/ -v
```
~350 Tests decken Sicherheit, Authentifizierung, API-Endpunkte, E-Mail, Kalender und mehr ab.
---
## 🗂️ Projektstruktur
```
Odysee-MacOS-App/
├── app.py # Web-Application (FastAPI/Starlette)
├── src/ # Kernlogik (LLM, Agent, Chat, MCP, Search…)
├── routes/ # API-Routen (Chat, Cookbook, Email, Kalender…)
├── services/ # Hintergrunddienste (Memory, Search, Research…)
├── static/ # Frontend (JS/CSS/HTML)
├── scripts/ # CLI-Werkzeuge & Helfer
├── tests/ # ~350 Tests
├── core/ # Auth, Datenbank, Middleware
├── data/ # Laufzeitdaten (wird bei Erststart befüllt)
├── assets/ # Icons & Ressourcen
└── dist/ # Build-Ausgabe (.app/.dmg)
```
---
## 🔒 Sicherheit
- **Lokale Installation** – Keine Cloud-Zwangsregistrierung
- **Authentifizierung** – Integriertes Auth-System mit Session-Management
- **API-Key-Speicher** – Verschlüsselt in der Datenbank
- **SSRF-Schutz** – Private-IP-Erkennung, Link-Sanitisierung
- **Regelmässige Audits** – Siehe `THREAT_MODEL.md` und `SECURITY.md`
---
## 📜 Lizenz
**MIT** – siehe [LICENSE](LICENSE) und [ACKNOWLEDGMENTS.md](ACKNOWLEDGMENTS.md).
Ursprünglich basiert auf [Odysseus](https://github.com/pewdiepie-archdaemon/odysseus) (ebenfalls MIT).
---
## 💡 Verwandte Projekte
- [Odysseus (Original)](https://github.com/pewdiepie-archdaemon/odysseus) – Ursprüngliches Projekt
- [LM Studio](https://lmstudio.ai) – Lokale LLMs betreiben
- [Ollama](https://ollama.com) – Einfache lokale LLM-Ausführung
---
*Made with 🏛️ auf einem Mac in Deutschland*
