Zum Inhalt
Rechenknecht

Plugins und Modelle

Was Rechenknecht von Haus aus kann, wie man eigene Werkzeuge in Python ergänzt und welche Modelle dahinter arbeiten können.

Überblick über die Fähigkeiten, die Modelle und das Bauen eigener Plugins.

Fähigkeiten

Jede eingebaute Fähigkeit ist ein Plugin mit eigener Bezeichnung und festen Grenzen. Die Tabelle nennt die Bezeichnung und die wichtigsten Regeln. Eine Erklärung für Anwender steht auf der Übersichtsseite.

Eingebaute Fähigkeiten
NameBeschreibung
adminreconOffene Admin- und API-Ports sowie erreichbare Pfade eines eigenen Geräts im Heimnetz, nur lesend, ohne aktiven Angriff.
downloadLädt Dateien mit Fortsetzen und parallelen Teilen. Nur öffentliche Adressen, Ablage im Ordner Download/Rechenknecht.
homeassistantSpricht Home Assistant über die REST-Schnittstelle an. Adresse und Token stehen nur in den App-Einstellungen. Dienstaufrufe erst nach Bestätigung.
lautheitMisst die Lautheit nach EBU R128, rein lokal.
netzscanZerstörungsfreier Scan des eigenen Heimnetzes: findet alle Geräte im WLAN-Subnetz (Router, PCs, Handys, Drucker, NAS, Smart Home, Kameras) per Verbindungsaufbau, Banner, mDNS, SSDP/UPnP und ONVIF. Dazu die Modi wlan, sicherheit, selbst und bluetooth. Keine Anmeldungen, keine Passwortproben, höchstens 32 Verbindungen gleichzeitig.
pruefenZerstörungsfreie Prüfungen mit GET, HEAD und Verbindungsaufbau, mit Pausen. Keine Passwortproben, keine Ausnutzung.
rechercheWebsuche mit Suchregeln nach ddgs 9.16.1 (MIT-Lizenz), übertragen als CSS-Auswahl.
rueckfrageFragt per Benachrichtigung zurück, mit Knöpfen, Freitext und optional einem Bild. Nur auf vertrauten Geräten.
sprechenSprachausgabe über die Offline-Stimmen des Geräts. Keine Daten verlassen das Handy.
torsucheSuche über Ahmia durch einen lokalen Tor-Proxy (Orbot). Nur Text, nur .onion, nur auf ausdrücklichen Auftrag, mit Sperrliste.
waybackFragt die Wayback Machine ab. Anfragen gehen nur an archive.org, nie an die Seite selbst. Archivieren nur nach Rückfrage.
webfotoBildschirmfoto einer Webseite über eine WebView ohne Fenster. Alle Anfragen laufen über den Adressfilter der App.
webserverStatischer Webserver für Ordner oder ZIP im eigenen WLAN oder Hotspot: nur GET und HEAD, nur der gewählte Ordner, schaltet sich selbst ab.
webtestWebseiten-Test mit lesenden Anfragen (GET, HEAD) und DNS-Abfragen. Kein JavaScript, keine Cookies, keine Formulare.
plauderknechtIRC-Chat in der App, hält die Verbindung im Hintergrund, auch über einen Bouncer (soju) mit mehreren Netzen und Kennungen. Nur Verbindung und Chat; Konten (NickServ) richtet der Nutzer selbst ein, die App registriert keine.
dateiLesen und Schreiben in einer app-privaten Ablage für Berichte, Notizen und Zwischenergebnisse. Nur der eigene Ablage-Ordner, kein Zugriff aufs übrige Dateisystem.

Eigene Plugins bauen

Ein Plugin ist eine einzelne .py-Datei. Der Server bietet sie als Werkzeug an, und das gewählte Modell ruft sie bei Bedarf auf.

Die Datei besteht aus vier Teilen: NAME ist der Kurzname, klein und ohne Leerzeichen. BESCHREIBUNG sagt in ein, zwei Sätzen, was das Werkzeug tut und wann man es nimmt, denn danach wählt das Modell aus. SCHEMA beschreibt die Eingabe als JSON-Schema. ausfuehren(args) bekommt die Eingabe als dict und gibt Text zurück.

Optional gibt es NUR_LESEN = True. Das setzt man nur, wenn das Plugin nichts verändert und nichts verschickt. Dann läuft es ohne Rückfrage. Ohne diese Angabe fragt die App vor jedem Aufruf einmal nach.

Ebenfalls optional: RECHTE nennt, was das Plugin braucht, als Teilmenge von ["netz", "dateien", "shell"]. DATEIEN = ["~/pfad", …] listet absolute Pfade (oder mit ~), die zusätzlich beschreibbar sein sollen. ZEIT_S setzt das Zeitlimit eines Aufrufs in Sekunden (Standard 60, höchstens 600), SPEICHER_MB die Speichergrenze (Standard 1024). Der Server liest diese Angaben, ohne die Datei auszuführen; es müssen also einfache Zuweisungen mit festen Werten sein. Berechnete Werte funktionieren auch, dann startet der Server das Plugin einmal zum Beschreiben (höchstens 15 Sekunden) und merkt sich das Ergebnis, bis die Datei sich ändert.

Die Datei kommt nach ~/.config/rechenknecht/plugins/, abweichend per Umgebungsvariable RK_PLUGINS. Dateinamen mit _ am Anfang werden nicht als Plugin geladen und taugen für gemeinsame Hilfsfunktionen. Ein Neustart ist nicht nötig, Plugins werden bei jedem Aufruf neu eingelesen. Ein fehlerhaftes Plugin blockiert die anderen nicht.

NAME = "dateien_zaehlen"
BESCHREIBUNG = "Zählt Dateien in einem Ordner."
NUR_LESEN = True
SCHEMA = {
    "type": "object",
    "properties": {
        "pfad": {"type": "string"},
    },
    "required": ["pfad"],
}

from pathlib import Path

def ausfuehren(args):
    p = Path(args.get("pfad", "")).expanduser()
    if not p.is_dir():
        return f"Kein Ordner: {p}"
    n = sum(1 for _ in p.iterdir())
    return f"{p}: {n} Einträge"

Rückgabe ist immer ein String, länger als 12 000 Zeichen wird gekürzt. Eine Ausnahme in ausfuehren wird abgefangen und als „Plugin-Fehler“ gemeldet.

Nur für eigene, vertraute Plugins

Fremden Code gehört nicht in diesen Ordner. Was ein Plugin nach draußen schickt, bestimmt allein der Code. Werte aus dem Netz gelten für das Modell als ungeprüfte Daten, nie als Anweisung.

Eigener Prozess. Ein Plugin läuft nicht im Server, sondern in einem eigenen Python-Prozess (python -I). Der Server importiert nichts davon. Eingabe und Ausgabe laufen als JSON. Je Aufruf gelten: Zeitlimit (ZEIT_S), Speichergrenze, CPU-Zeit, höchstens 256 offene Dateien, höchstens 50 MB je geschriebener Datei und eine eigene Prozessgruppe, die bei Zeitüberschreitung samt Unterprozessen beendet wird. Die Umgebung enthält nur PATH, HOME, LANG und RK_HOME (Server-Variablen und Token sind nicht sichtbar). HOME und das Arbeitsverzeichnis sind der Ordner ~/.local/share/rechenknecht/plugin-arbeit/<name>. Für Python-Code selbst bleibt ~ (expanduser, Path.home()) der echte Home-Ordner, damit bestehende Plugins unverändert laufen; Unterprozesse sehen das Arbeitsverzeichnis als HOME. Die Rückgabe wird auf 12 000 Zeichen gekürzt; Ausgaben mit print gehören nicht zum Ergebnis.

Käfig mit bubblewrap. Ist bwrap installiert und funktionsfähig und gibt das Plugin RECHTE an, startet der Läufer darin: Dateisystem nur lesend, Arbeitsordner beschreibbar, /tmp leer im Arbeitsspeicher, eigene Namensräume. Das Netz ist nur mit "netz" erreichbar. Mit "dateien" sind zusätzlich die Pfade aus DATEIEN beschreibbar. Das Home-Verzeichnis des Server-Nutzers ist im Käfig leer; LESEN = ["~/.ssh/mein_schluessel"] macht einzelne Dateien oder Ordner daraus wieder sichtbar, aber nur lesbar. Je Nutzer gilt außerdem eine Grenze für Unterprozesse. Die App und die Werkzeugliste zeigen je Plugin die Rechte, nur_lesen, ob ein Käfig wirkt („im Käfig (bubblewrap)“ oder „ohne Käfig (bubblewrap fehlt)“) und den letzten Lauf.

Keine doppelten Prüfungen. Was jedes Plugin bräuchte, erledigt der Rahmen einmal für alle. Jede Ausgabe wird vor der Weitergabe an Merlin geschwärzt: private Schlüssel, Bearer- und Basic-Angaben, Token-Formate, Werte hinter password=, token=, api_key= und Zugangsdaten in Adressen. Mit SCHWAERZEN = "streng" werden zusätzlich IP- und MAC-Adressen sowie E-Mail-Adressen ersetzt, und zwar durch feste Platzhalter je Ausgabe (IP-1, IP-2 …), damit Zusammenhänge erkennbar bleiben. Für lesende Diagnose gibt es den Helfer rk_hilfe.ssh: Er kennt nur eine feste Liste von Befehlen (Laufzeit, Speicher, Platten, ausgefallene Dienste, Fehler- und Kernel-Journal, Status und Journal eines Dienstes, Ende einer Datei unter /var/log). Jeder Wert wird gegen ein festes Muster geprüft. Lokal läuft das ohne Shell, per SSH nur mit eigenem Schlüssel und known_hosts. Dieselbe Datei lässt sich auf dem Zielrechner als erzwungener Befehl in authorized_keys eintragen (restrict,command="/usr/bin/python3 …/ssh.py --ziel"); dann führt auch der Zielrechner nur diese Befehle aus. Plugins enthalten nur ihre Fachlogik.

Beispiel LogSherlock. Das Server-Plugin logsherlock.py liest Logs dieses Rechners oder eines eigenen Servers per SSH. Es erkennt Speichermangel, volle Platten, Datenträgerfehler, Abstürze, Neustart-Schleifen, ausgefallene Dienste, abgelehnte Verbindungen, HTTP-5xx, gehäufte Anmeldefehler und Zertifikatsprobleme. Ereignisse, die innerhalb von fünf Minuten zusammenfallen, ordnet es als mögliche Ursache zu, ausdrücklich als Vermutung. Es liest nur und verändert nichts. Für das Systemjournal braucht der Server-Nutzer die Gruppe systemd-journal.

Host-Liste. Die Datei ~/.config/rechenknecht/hosts.json (Pfad per RK_HOSTS änderbar) beschreibt die eigenen Rechner einmal für alle Plugins: name, adresse, tags, optional ssh (nutzer@rechner), mac (für Wake-on-LAN) und pruefen mit ping, ports, http und zertifikat (host:port). Beim Laden wird jeder Eintrag geprüft; Ungültiges wird übersprungen und als Hinweis gemeldet. Im Käfig ist die Datei immer eingebunden, aber nur lesbar. Eine Vorlage liegt als hosts.beispiel.json bei den Server-Plugins. Plugins nutzen rk_hilfe.hosts (laden, finde).

Weitere Befehle in rk_hilfe.ssh. Alle nur lesend, mit derselben Prüfung: container_liste, container_logs, container_status (nur Zustand, Neustarts, Health, Abbild), podman_liste, traceroute, mtr, dns (Satztyp A, AAAA, MX, TXT, NS, CNAME, SOA oder PTR) und ping (1 bis 10 Pakete). Hostnamen und Container-Namen dürfen nie mit einem Bindestrich beginnen. Fehlt ein Programm, kommt eine verständliche Meldung statt eines Absturzes. Das Zertifikat liest rk_hilfe.netz.zertifikat_ablauf(host, port) in Python (Ablauf und Aussteller, ohne Kettenprüfung); dort liegen auch Port- und HTTP-Prüfung.

Zeitplan für Server-Plugins. Mit ZEITPLAN = {"alle_minuten": 15, "melden": "bei_treffer", "args": {}} sagt ein Plugin, dass es regelmäßig laufen soll. alle_minuten ist mindestens 15, melden ist immer, bei_treffer (Standard) oder nie. Erlaubt ist das nur bei NUR_LESEN = True; sonst wird der Zeitplan ignoriert und als Hinweis ausgewiesen. Die Plugin-Liste liefert ihn als zeitplan (ohne Zeitplan null). Treffer-Konvention: Die erste Zeile der Rückgabe lautet STATUS: OK oder STATUS: PROBLEM – Kurztext; gemeldet wird bei „bei_treffer“, wenn sie mit STATUS: PROBLEM beginnt.

Vier Server-Plugins auf dieser Grundlage. waechter.py prüft alle Hosts mit pruefen (Ping, Port, Webseite mit Antwortzeit, Zertifikat unter 14 Tagen Restlaufzeit) und meldet nur Änderungen: neu ausgefallen oder wieder da. container.py zeigt Docker-Container lokal oder auf einem Host mit ssh, mit Neustart-Zählern, Health und auffälligen Exit-Codes, auf Wunsch die letzten Logzeilen; Fehlerbilder in Logs erkennt LogSherlock. netzdiagnose.py führt ping, traceroute, mtr, dns und zertifikat für einen Host aus und fasst Paketverlust, Latenz und Sprünge zusammen. wol.py weckt einen Host mit hinterlegter mac per Magic Packet; es ist nicht als „nur lesen“ markiert, die App fragt also vor dem Senden nach.

Käfig für alle. Jedes Server-Plugin läuft im Käfig. Fehlt RECHTE, gilt der strengste Käfig: kein Netz, nichts beschreibbar außer dem eigenen Arbeitsordner, das Home-Verzeichnis leer. Im Käfig sind außerdem /run und /tmp leer, damit ein Plugin keine Verbindung zu Diensten außerhalb aufbauen kann, etwa zum Benutzer-D-Bus oder zu einem ssh- oder gpg-Agenten. Prozesse außerhalb des Käfigs sind unsichtbar. Eine Ausnahme kann nur der Admin eintragen, und zwar mit dem Plugin-Namen in ~/.config/rechenknecht/plugins-ohne-kaefig.txt. Ein Plugin kann sich nicht selbst befreien. Fehlt bubblewrap, startet ein Plugin ohne diese Ausnahme gar nicht, statt still ungeschützt zu laufen.

Überwachung auf dem Server. Plugins mit ZEITPLAN führt der Server selbst im Takt aus, sobald man die Überwachung in der App einschaltet. Er ist also nicht darauf angewiesen, dass das Handy wach ist. Das Handy holt die Ergebnisse ab und meldet nur neue Probleme.

Grenzen. Die Prozessgrenzen verhindern Hänger und Speicherfraß, sie sind kein vollständiger Schutz gegen gezielt schädlichen Code. Das Recht "shell" ist nur eine Angabe: Unterprozesse lassen sich ohne seccomp nicht sperren, sie laufen im Käfig aber mit denselben Einschränkungen. Die Speichergrenze zählt den Adressraum, große Bibliotheken brauchen gegebenenfalls ein höheres SPEICHER_MB. RECHTE sagt, was das Plugin braucht. Der Käfig setzt das durch, ersetzt aber nicht das Lesen fremden Codes vor dem Einspielen.

Einrichtung in der App: unter „Eigene KI und Server“ einen MCP-Server mit der Adresse http://<IP-des-Servers>:8790/mcp und dem Verwaltungs-Token eintragen. Danach erscheinen die Plugins in der Werkzeugliste.

Plugin direkt in der App installieren

Skript-Plugins für das Handy lassen sich ohne Server und ohne neue App-Version einspielen. In der App unter „Plugins“ im Abschnitt „EchtOS-Plugins“ gibt es „Aus Datei …“ (System-Dateiauswahl) und „Aus Adresse …“ (https-Adresse einer ZIP-Datei, ohne Weiterleitungen). Das Plugin liegt danach app-privat auf dem Handy und ist zunächst aus. Beim Einschalten zeigt die App eine Übersicht der Rechte; erst nach „Einschalten“ kann Merlin das Plugin nutzen.

Die ZIP-Datei enthält eine plugin.json und die Skriptdateien, entweder direkt im Hauptordner oder in genau einem Unterordner. Höchstens 5 MB entpackt und 200 Dateien. Dateinamen bestehen aus Buchstaben, Ziffern, _, - und .; Pfade mit .., absolute Pfade und versteckte Dateien weist die App ab. Gibt es schon ein Server-Plugin gleichen Namens, fragt die App vor dem Ersetzen nach.

Felder der plugin.json
FeldBedeutung
nameNur a–z, 0–9, _, 2 bis 40 Zeichen. Namen eingebauter Funktionen und tor sind reserviert.
beschreibungEin, zwei Sätze, wann das Werkzeug passt. Danach wählt Merlin aus.
schemaEingabe als JSON-Schema.
skriptHauptskript (.py oder Shell). Bekommt die Eingabe als JSON im ersten Argument und gibt Text aus.
nur_lesentrue, wenn das Plugin nichts verändert und nichts verschickt. Sonst fragt die App vor jedem Aufruf nach.
shellechtos (Standard, abgeschottetes Linux in der App) oder system (Android-Shell mit den Rechten der App, nur für Code, dem man vertraut).
tortrue leitet den Verkehr über Tor, nur mit echtos.
braucht_pip, braucht_pkgPython- und Systempakete, die im EchtOS-Gast vorhanden sein müssen. Die App zeigt sie in der Rechte-Übersicht.
zeitplanOptional, siehe unten.
mein_plugin.zip
  plugin.json
  skript.py
  daten.json
{
  "name": "preis_beobachter",
  "beschreibung": "Prüft den Preis einer Seite.",
  "schema": {
    "type": "object",
    "properties": {"url": {"type": "string"}},
    "required": ["url"]
  },
  "nur_lesen": true,
  "shell": "echtos",
  "skript": "skript.py",
  "braucht_pip": ["requests"],
  "zeitplan": {
    "alle_minuten": 60,
    "args": {"url": "https://example.org"},
    "melden": "bei_treffer"
  }
}

Zeitplan

Mit zeitplan kann ein Plugin regelmäßig von selbst laufen: alle_minuten (mindestens 15), args (die Eingabe für jeden Lauf) und melden. Bei immer kommt nach jedem Lauf eine Benachrichtigung, bei bei_treffer nur, wenn etwas gefunden wurde, bei nie keine; Standard ist bei_treffer. Als „kein Treffer“ gilt eine leere Ausgabe oder eine, die mit „Keine“, „Kein“, „Nichts“, „0 Treffer“ oder „Fehler“ beginnt.

Der Zeitplan läuft nur, wenn der Nutzer in der Plugin-Liste den eigenen Zeitplan-Schalter einschaltet (Standard: aus) und das Plugin selbst aktiv ist. Er ist gesperrt für Plugins, die nicht nur_lesen sind. Die Liste zeigt den letzten Lauf mit der ersten Ausgabezeile. Android startet zeitgesteuerte Läufe ungefähr, nicht auf die Minute, und nur bei nicht schwachem Akku.

Rechte und Verantwortung

Die Angabe nur_lesen stammt vom Plugin selbst und ist keine Prüfung. Skripte können das Netz nutzen, was sie senden, bestimmt allein ihr Code. Pakete aus fremder Quelle vor dem Einschalten ansehen. „Entfernen“ in der Liste löscht das Plugin samt Kopien auf dem Handy.

Modelle

Welches Modell antwortet, lässt sich in der App wählen. Die Werkzeuge stehen jedem davon zur Verfügung.

Modelle und wo sie laufen
NameWofürLäuft aufHinweis
GemmaTexte, Bilder und Sprache verstehenHandyLäuft lokal auf dem Gerät. Die Datei kommt vom eigenen Server.
MerlinTexte, eigenes ModellHandyBeta.
Qwen CoderCode, TextHandyBeta.
Claude SonnetSchwere AufgabenRechnerLäuft auf dem Rechenknecht-Server.
Eigene KI / ServerFrei wählbareigener ServerOpenAI-kompatible Schnittstelle oder MCP, frei eintragbar.

Modell anschließen

Welches Modell antwortet, wählt man in der App unter „Modelle“ — die Werkzeuge stehen jedem zur Verfügung. Statt der lokalen Modelle lässt sich eine eigene KI eintragen: jede OpenAI-kompatible Schnittstelle (Ollama oder LM Studio im eigenen Netz, OpenAI, Google Gemini, OpenRouter) oder ein MCP-Server, mit Adresse und, je nach Anbieter, einem API-Schlüssel. Der Schlüssel liegt verschlüsselt im Android Keystore und geht nur an die eingetragene Adresse; Klartext-http ist nur im eigenen Netz erlaubt.

Claude Sonnet läuft nicht im Handy, sondern auf dem Rechenknecht-Server — das Handy fragt dort an. Ein eigenes Modell im Format .litertlm lässt sich lokal aufs Handy laden (als „nicht von echtor geprüft“ gekennzeichnet).

Einzelheiten zu Schlüsseln, Datenschutz und Platzhaltern bei KIs im Internet stehen auf der Übersichtsseite unter „Eigene KI anschließen“. Wie Merlin zwischen lokalem und großem Modell entscheidet, beschreibt die Seite KI-Aufbau.