🐠 Clownfischserver

Wie der Clownfisch in seiner Anemone lebt – geschützt, autonom, und beißt überraschend hart.

Ein selbst-hostbarer, KI-gestützter Server-Manager der ausschließlich über Telegram kommuniziert. Kein Dashboard, kein Web-UI, keine Cloud. Nur du und dein Server – über eine Chat-Nachricht.

---

🐟 Warum "Clownfisch"?

Der Clownfisch lebt in seiner Anemone – einem der wenigen Orte im Ozean die für andere Fische tödlich sind. Er verlässt sie kaum, schützt sie aktiv, und fühlt sich darin vollkommen sicher.

Genauso lebt der Clownfischserver in seinem Server (seiner Anemone):

• Er schirmt alles ab was nicht sein muss
• SSH bleibt standardmäßig zu – nur wer das richtige Klopfmuster kennt kommt rein
• Die KI entscheidet was sicher ist und was nicht
• Und wie der echte Clownfisch: beißt er überraschend hart wenn nötig 🐠

---

Was ist das?

Clownfischserver verwandelt einen Linux-Server in einen vollautonomen, Telegram-gesteuerten Assistenten. Du schreibst ihm in natürlicher Sprache – er versteht, generiert Befehle, erstellt Scripts, und verwaltet deinen Server.

Das Ziel: Server-Administration so einfach wie eine Chat-Nachricht. Heute ein Server, morgen eine ganze Farm.

Kein SCP. Kein Dashboard. Kein Cloud-Zwang. Nur Telegram.

---

Features

• 🤖 Telegram Bot als primäres Interface – von überall, auch vom Handy
• 🧠 Dual-Model KI – Code-Modell (qwen2.5-coder) für Befehle + Chat-Modell (gemma3) für Konversation
• 🔧 /shell + /ja – KI generiert Shell-Befehle, du bestätigst vor der Ausführung
• 🛠️ /code + Aider – autonome Code- und Script-Generierung direkt auf dem Server
• 💬 Natürlicher Chat – Fragen stellen, Erklärungen bekommen, übersetzen lassen
• 📸 Automatische Snapshots vor destruktiven Aktionen (tar.gz mit Keep/Unkeep + Paketliste)
• 🔐 Port-Knocking SSH als sicherer Backup-Zugang (knockd) mit Telegram-Benachrichtigung
• 🔔 Benachrichtigungen – SSH-Zugang, Server-Boot, Knock-Versuche via Telegram
• 📦 Self-Update via Telegram – ZIP an den Bot schicken, fertig (inkl. systemd-Services)
• ☁️ OpenRouter Fallback – kostenlose Cloud-Modelle als Backup wenn Ollama nicht verfügbar
• 👤 Eigener User – beliebiger Name, passwordless sudo, wird überall korrekt eingesetzt
• 🌍 Mehrsprachig – antwortet in der Sprache in der du schreibst
• 🐧 Multi-Distro – Debian, Ubuntu, Fedora, Arch (Installer)
• 🔒 DSGVO by design – lokal ist Standard, Cloud ist Opt-in

---

Schnellstart

# Frisches Ubuntu/Debian – als root:
wget https://github.com/mehlzoerwer-claude/clownfischserver/archive/refs/heads/main.zip
unzip main.zip && cd clownfischserver-main
bash install.sh

Der Installer führt dich durch alles – Schritt für Schritt, mit Erklärungen.

---

Installation

Was du brauchst

• Frischer Ubuntu 22/24 oder Debian 12/13 VPS (min. 8GB RAM empfohlen, 20GB Disk)
• Root SSH-Zugang für die Installation
• Ein Telegram-Account (5 Minuten für Bot-Setup)

RAM-Empfehlung

RAM	Coder-Modell	Chat-Modell	Gesamt ca.
8-12 GB	qwen2.5-coder:3b	gemma3:1b	~3 GB
16+ GB	qwen2.5-coder:7b	gemma3:4b	~8 GB

Der Installer

[1/8] Systemcheck          → RAM, Disk, Distro-Erkennung
[2/8] Pakete               → alles Nötige mit Spinner
[3/8] User einrichten      → eigener User oder vorhandenen nutzen
[4/8] SSH + Firewall       → Port-Knocking, ufw, SSH bleibt offen
[5/8] Ollama               → Dual-Model KI-Setup (Coder + Chat)
[6/8] Python + Aider       → Bot-Umgebung + Code-Agent
[7/8] Telegram             → geführtes Bot-Setup mit BotFather
[8/8] Service starten      → systemd + Boot-Notification

Update (wenn bereits installiert)

bash install.sh
# → erkennt laufenden Service
# → [1] Update  [2] Neuinstallation  [3] Abbrechen

Oder noch einfacher: ZIP direkt an den Bot schicken – Self-Update!

---

Nutzung

Bot-Befehle

Befehl	Beschreibung
/shell <beschreibung>	KI generiert Shell-Befehl aus natürlicher Sprache
/ja	Letzten vorgeschlagenen Befehl ausführen
/code <aufgabe>	Aider erstellt/bearbeitet Code und Scripts
/run <befehl>	Direkte Shell – kein Ollama, kein Bestätigen
/status	CPU, RAM, Disk, Top-Prozesse
/snapshots	Alle Snapshots anzeigen
/snapshot [label]	Manuell Snapshot erstellen
/snapshot keep <n>	Snapshot als wichtig markieren
/snapshot delete <n>	Snapshot löschen
/rollback <n>	Zu einem Snapshot zurückkehren
/ssh open [ip]	SSH via ufw öffnen (für alle oder eine IP)
/ssh close [ip]	SSH wieder sperren
/start / /help	Bot-Info und Befehlsübersicht

Freitext-Chat

Einfach schreiben – ohne Befehl. Der Bot antwortet als Chat-Partner:

"Was ist ein Reverse Proxy?"
"Übersetze das ins Englische: ..."
"Erkläre mir den Unterschied zwischen apt und snap"
"Welche Services laufen gerade auf meinem Server?"

Workflow: /shell + /ja

Du:   /shell zeig mir die größten Dateien auf dem Server
Bot:  🔧 Vorgeschlagener Befehl:
      du -ah / | sort -rh | head -20
      → Mit /ja ausführen oder einfach ignorieren.
Du:   /ja
Bot:  ✅ Ergebnis: ...

Workflow: /code

Du:   /code erstelle ein bash script das alte Logs älter als 30 Tage löscht
Bot:  🛠️ Aider Ergebnis:
      ✅ Aider Task abgeschlossen
      Applied edit to cleanup-logs.sh

Self-Update

ZIP-Datei direkt an den Bot schicken → Bot erstellt Snapshot → installiert Update → startet neu.

---

Architektur

                         ┌─────────────────────┐
                         │     Telegram Bot     │
                         │      (bot.py)        │
                         └──────┬──────┬────────┘
                                │      │
              ┌─────────────────┤      ├─────────────────┐
              ▼                 ▼      ▼                 ▼
     ┌────────────────┐ ┌────────────┐ ┌──────────────────┐
     │  ollama_client  │ │  shell.py  │ │  aider_wrapper   │
     │   (Dual-Model)  │ │ (run_shell)│ │  (Code-Agent)    │
     └───────┬────┬────┘ └────────────┘ └──────────────────┘
             │    │
    ┌────────┘    └────────┐
    ▼                      ▼
┌──────────┐      ┌──────────────┐
│ Chat-Model│      │ Coder-Model  │
│ (gemma3)  │      │(qwen2.5-coder)│
└──────────┘      └──────────────┘

Weitere Module:
  snapshot.py       – Backup-System (tar.gz, keep/unkeep, auto-cleanup)
  knock_notify.py   – SSH Port-Knocking Alerts
  boot_notify.py    – Server-Neustart Benachrichtigung

---

Sicherheit

Port-Knocking

SSH ist standardmäßig durch ufw blockiert. Zugang via Klopf-Sequenz:

# Oeffnen:    7000 -> 8000 -> 9000
knock SERVER_IP 7000 8000 9000

# Schliessen: 9000 -> 8000 -> 7000
knock SERVER_IP 9000 8000 7000

Bei jedem Knock kommt eine Telegram-Benachrichtigung mit IP und Zeitstempel.

KI-gestützte Befehlsgenerierung

/shell installiere nginx
  → KI generiert: apt install -y nginx
  → Gefährlich? Nein → Vorschlag anzeigen
  → /ja zum Ausführen, oder ignorieren

/shell lösche alles in /etc
  → KI generiert: rm -rf /etc/*
  → Gefährlich? JA → Verweigert mit Erklärung

Kein Befehl wird ohne Bestätigung ausgeführt. Gefährliche Befehle werden immer verweigert.

Snapshot-System

Vor destruktiven Aktionen automatischer Snapshot (tar.gz). Wichtige Snapshots können mit /snapshot keep markiert werden und werden nie automatisch gelöscht.

Boot-Notification

Nach jedem Server-Neustart bekommst du eine Telegram-Nachricht mit Status aller Dienste (Clownfisch, Ollama, ufw, SSH, Cron) – nach 2 Minuten, wenn alles hochgefahren ist.

---

Roadmap

Fertig (v0.1 – v0.5.0)

• Basis-Installer mit geführtem Setup (8 Schritte)
• Telegram Bot mit Auth Guard (Single-User)
• Dual-Model KI: Coder (qwen2.5-coder) + Chat (gemma3/gemma4)
• /shell + /ja – Befehlsgenerierung mit Bestätigung (non-interaktive Befehle)
• /code – Aider Code-Agent für autonome Script-Erstellung (Smart Prompt)
• /run – Direkte Shell ohne KI
• /status – Systemübersicht (CPU, RAM, Disk, Prozesse)
• /ssh open/close – ufw-basierter SSH-Zugang
• Freitext-Chat mit History (letzte 10 Exchanges)
• Snapshot-System (tar.gz, keep/unkeep, auto-cleanup max 20, Paketliste)
• /snapshot, /snapshots, /rollback (inkl. Workspace)
• Port-Knocking SSH (knockd) mit Telegram-Benachrichtigung
• Boot-Notification nach Server-Neustart (Dienste-Status)
• Self-Update via Telegram ZIP (inkl. systemd-Services + User-Patch)
• Update-Modus im Installer (mit MGMT_USER aus .env)
• Multi-Distro Installer (apt/dnf/pacman)
• Ollama Warmup im Hintergrund (Bot sofort bereit)
• OpenRouter Free Fallback – kostenlose Cloud-Modelle wenn Ollama nicht verfügbar
• Interaktiver Update-Dialog (OpenRouter Key Eingabe via Telegram)
• OLLAMA_NUM_CTX konfigurierbar (4K–32K, RAM-basierte Empfehlung im Installer)
• Safe Telegram Output (Markdown-Fallback bei Parse-Fehlern)
• Lange Antworten werden in Teile gesplittet (kein Abschneiden)
• Mehrsprachig (antwortet in der Sprache des Nutzers)
• MGMT_USER Regex-Patch (beliebiger Username funktioniert überall)
• Security-Analyse dokumentiert (Schwachstellen + Maßnahmen in CLOWNFISCHSERVER.md)
• DSGVO-Regel: .env nur per SSH, nie über Telegram lesbar
• Projekt-Kontext-Datei (CLOWNFISCHSERVER.md) für KI-gestütztes Pair-Programming

v0.5.0 – Cleanup & Stabilität (aktuelles Release)

Bugfixes & Aufräumarbeiten (dieser Release):

• Totes Vault/MCP-Context-System komplett entfernt (war nie verdrahtet, verify=False-Lücke)
• Privacy-Fix: Chat-Nachrichten gingen via Vault-Suche an externe Endpoints → entfernt
• /code Filepath-Logik: fragiler Ternary-Ausdruck sauber umgeschrieben (kein Crash bei leerem Task)
• Aider-Model-Default vereinheitlicht (zieht sich OLLAMA_MODEL aus der Umgebung)
• Irreführende „Token-Optimization"-Logs (Anthropic-Kosten/Obsidian) aus dem Start-Log entfernt

Sicherheit & DSGVO (geplant):

• Sensitive Dateien über Telegram blockieren (.env, shadow, Keys)
• Output-Sanitizer: API Keys/Tokens in jeder Bot-Antwort maskieren
• Log-Sanitizer: Keine Secrets im Audit-Log
• Audit-Log: Jeder Befehl mit Timestamp (DSGVO Art. 5/32)
• Self-Update Hardening: SHA256-Hash anzeigen, Admin bestätigt
• .env Permissions-Check beim Bot-Start
• bot.log, .aider.chat.history.md, bash_history aus Snapshots excluden
• Rate-Limiting: Max 30 Befehle/Minute
• Session-Timeout: Nach 30 Min Inaktivität → 2FA erneut nötig
• 2FA bei kritischen Aktionen (TOTP/Mail/zweiter Bot)
• Persönlicher Code-Offset (SECURITY_OFFSET in .env)

Features:

• Snapshot-Scheduling (/snapshot schedule daily 03:00)
• Snapshot-Export als ZIP via Telegram (/snapshot export <n>)
• /logs – Systemlogs direkt im Bot
• /docker – Docker Container Management
• Port-Knocking Sequenz im Installer wählbar
• Verschlüsselte Snapshots (SNAPSHOT_PASSWORD)
• Open Interpreter als Aider-Alternative evaluieren

Quick-Win Security:

• Panik-Wort: Admin-definiertes Wort → Bot löscht .env, sperrt alles
• Honeypot-Befehle: Fake-Commands die Eindringlinge verraten
• Selbstzerstörende Nachrichten: Bot löscht eigene Outputs nach X Minuten
• Rollback-Bombe: 3x falscher 2FA → auto-Rollback + SSH sperren
• Dead Man's Switch: Kein Lebenszeichen in 24h → Bot sperrt sich

v0.6.0 – Multi-Server

• Ein Bot steuert mehrere Server
• Zentrale Snapshot-Verwaltung
• Serverpark-Übersicht und -Steuerung
• Mehrere Nutzer mit unterschiedlichen Rechten

v0.7.0 – DSGVO-bewusster Backup-Manager

• /backup configs → immer erlaubt
• /backup app → eigene Anwendungsdaten
• /backup db → Warnung + Bestätigung bei personenbezogenen Daten
• Lokale KI bewertet ob Daten DSGVO-relevant sein könnten

v0.8.0 – Erweiterte Cloud-API Integration

• Wahl zwischen Free- und Premium-Modellen auf OpenRouter
• Direkte Anthropic/OpenAI API-Anbindung (neben OpenRouter)
• Admin steuert pro Befehlstyp: lokal oder Cloud
• Kosten-Tracking für Cloud-API-Nutzung

v0.9.0 – Multi-Interface + Advanced Security

• Matrix/Element Connector (E2E-verschlüsselt, self-hosted)
• Web-UI mit HTTPS (self-hosted, Let's Encrypt)
• SSH-CLI als direktes Interface
• Fake-Modus + Distress-Code (falscher 2FA → stiller Alarm)
• Geo-Fencing (nur erlaubte Länder/IP-Bereiche)
• Buddy-System (zwei Admins für kritische Befehle)
• Verschlüsselter Rückkanal über Telegram

---

Langzeit-Vision 🚀

v1.0.0 – Intelligent Disaster Recovery

Server komplett aus Snapshot wiederherstellen – auch auf anderer Hardware oder in einer anderen Umgebung. Die KI analysiert den Snapshot und rekonstruiert die Umgebung.

"Stelle Server 3 auf Stand von gestern 02:00 Uhr wieder her."

Ziel: Open Source Alternative zu teuren Enterprise DR-Lösungen.

v2.0.0 – Cross-Distribution Server Migration

Die eigentliche Revolution: Ein Snapshot, jedes Zielsystem.

Der Clownfischserver versteht nicht nur Dateien, sondern die Logik eines Servers:

• Welche Pakete sind installiert und wofür?
• Welche Services laufen und wie sind sie konfiguriert?
• Welche Abhängigkeiten bestehen zwischen Komponenten?

Diese Logik ist distro-unabhängig. Ein Debian-Server mit nginx + PostgreSQL + Docker hat die gleiche Absicht wie ein Arch-Server mit denselben Diensten – nur andere Paketnamen, Pfade und Init-Systeme.

Ziel-Plattformen:

• Debian / Ubuntu (heute)
• Arch Linux
• Red Hat / Fedora / CentOS
• openSUSE
• FreeBSD
• Weitere UNIX-Systeme

Wie es funktioniert:

1. KI analysiert Snapshot und erstellt ein distro-neutrales "Server-Profil"
2. Profil beschreibt: Dienste, Konfigurationen, Daten, Netzwerk, Nutzer
3. Auf dem Zielsystem: KI übersetzt das Profil in native Befehle
4. apt install nginx → pacman -S nginx → pkg install nginx
5. Konfigurationen werden angepasst (Pfade, Syntax, Permissions)

"Migriere meinen Debian-Webserver auf Arch Linux."

Weltklasse Integration 🌍

Clownfischserver als Infrastruktur-Layer für die Weltklasse App – natürliche Sprachsteuerung des gesamten Server-Ökosystems. GDPR-konform, vollständig lokal, kein Cloud-Zwang.

---

"Angefangen als einfacher Telegram-Bot – gewachsen zu einer Vision." 🐠

---

Prinzipien 🛡️

1. Local AI first      – Lokal ist Standard. Cloud ist Opt-in.
2. Open Source always   – GPL-3.0, keine Ausnahmen
3. DSGVO by design     – Datenschutz ist kein Feature, es ist Pflicht
4. Security first      – SSH zu, KI prüft, Snapshots sichern
5. Einfachheit         – ein Mensch, ein Bot, ein Server
6. Distro-agnostisch   – Linux ist Linux. Die KI kennt den Unterschied.

Zur Cloud-Frage

Clownfischserver ist und bleibt local-first. Aber wir sind keine Puristen: wenn ein Admin einen OpenRouter-API-Key hat und ihn für komplexe Aufgaben nutzen will, soll er das können. Die Entscheidung liegt beim Admin, nicht beim Tool.

Was wir nicht tun:

• Cloud als Voraussetzung
• Daten automatisch an externe APIs senden
• Features hinter Cloud-APIs verstecken

Was wir ermöglichen (seit v0.4.12/v0.4.13):

• Optionaler OpenRouter API-Key in .env (kostenlos, keine Kreditkarte)
• Automatischer Fallback: Ollama Timeout → OpenRouter übernimmt
• Wenn Cloud ausfällt, funktioniert alles weiterhin lokal
• Setup direkt im Bot: ZIP schicken → Bot fragt nach Key → fertig

Als Admin entscheidest du – nicht das Tool.

---

Entwicklung

Entwickler: Mehlzoerwer-Claude

KI-Assistent: Dieses Projekt wurde mit Claude (Anthropic) als Pair-Programming Partner entwickelt. Claude ist der einzige nicht-Open-Source Teil dieser Zusammenarbeit. 😄

Philosophie: Open Source ohne Wenn und Aber. Wer's nutzt, muss es offen lassen (GPL-3.0).

---

Lizenz

GPL-3.0 - Keep it open. Always.

Copyright (C) 2025-2026 Mehlzoerwer-Claude

---

Danke an alle die Ollama, Aider, python-telegram-bot, knockd und ufw gebaut haben. Und an den echten Clownfisch – für die Inspiration. 🐠