Zum Hauptinhalt springen

Betrieb

Dienst, Ports, Proben

Veröffentlichungsdatum

23. September 2026

TippIn einem Satz

Famulus Notebook läuft als launchd-Dienst auf Port 5118 und ist über den Plattform-Proxy und Tailscale Serve erreichbar; ob er arbeitet, zeigt nur eine Probe gegen den laufenden Dienst.

1 Dienste, die zusammenarbeiten

Dienst Port Aufgabe für das Notebook
famulus-notebook 5118 Viewer, API, Blockausführung, Docs unter /docs
ai-query 5113 Anmerkungen, Lernzyklus, Golden-Manifest; Bibliothek für die Ausführung
ai-lektorat 5114 Überarbeitung des Fließtexts
Plattform-Proxy 5001 Pfad /famulus-notebook
Conductor 5401 nicht nötig; die Ausführung ruft ExecutionHarness.run im eigenen Prozess

Die Ports stehen im Portregister der Plattform (platform/registry/rules/ai-ports.mdc) und in platform/config/routes.yaml.

2 Der Dienst

Der launchd-Job heißt com.ai-platform.famulus-notebook. Er startet famulus-notebook serve --port 5118 --host 127.0.0.1 und startet den Prozess neu, wenn er endet. Auf dem mac-studio schreibt er seine Protokolle nach ~/ai-mac-studio/platform/logs/famulus-notebook.{out,err}.log; install.sh --launchd legt sie sonst unter ~/Library/Logs/famulus-notebook/ an.

launchctl kickstart -k gui/$(id -u)/com.ai-platform.famulus-notebook   # neu starten
launchctl print gui/$(id -u)/com.ai-platform.famulus-notebook | head    # Zustand

Nach einem neuen Viewer-Build genügt ein Neuladen der Seite; nach einer Änderung am Python-Code braucht es einen Neustart.

3 Wege von außen

Adresse ohne Token mit Token
http://127.0.0.1:5118/… alles alles
http://127.0.0.1:5001/famulus-notebook/… nur /notebook, /assets/ und /docs alles außer Anmerkungen
https://mac-studio.tail147011.ts.net/famulus-notebook/… nur /notebook, /assets/ und /docs alles außer Anmerkungen

Der Dienst hört nur auf 127.0.0.1. Proxy und Tailscale Serve laufen auf demselben Rechner und reichen die Anfrage weiter; der Dienst erkennt sie an den weitergegebenen Kopfzeilen und verlangt das Token.

4 Proben

Ob der Dienst arbeitet, zeigen diese Proben, nicht der Eintrag im Portregister und nicht der geladene Job:

nc -z 127.0.0.1 5118; echo $?                                         # 0
curl -s http://127.0.0.1:5118/api/health                              # notebooks, engine, viewer_built
curl -s -o /dev/null -w '%{http_code}\n' \
  https://mac-studio.tail147011.ts.net/famulus-notebook/api/health    # 401 ohne Token
curl -s -o /dev/null -w '%{http_code}\n' \
  -H "Authorization: Bearer $(cat ~/.config/famulus/token)" \
  https://mac-studio.tail147011.ts.net/famulus-notebook/api/health    # 200

/api/health meldet engine: false, wenn ai-agent-orchestrator oder ai-query nicht importierbar sind. Dann laufen Blöcke nicht am eigenen Rechner; jeder Block endet als Fehler mit diesem Grund, der Viewer arbeitet weiter.

Ohne PDAI-1 findet /api/collections keine Sammlungen (mounted: false). Ein Block, der eine Datenbank der Sammlung liest, endet dann als Fehler und nennt den fehlenden Pfad; ein leeres Ergebnis entsteht daraus nicht.

5 Konsistenz und Kohärenz

.venv/bin/famulus-notebook check                     # alle Pakete dieses Rechners
.venv/bin/famulus-notebook check site/projekte/kepler-anima-vis --json
curl -s 'http://127.0.0.1:5118/api/coherence?nb=kepler-anima-vis'

Die Prüfung meldet fünf Arten von Befund: veraltet (Eingaben seit dem letzten Lauf verändert), Urteil (fehlt oder nicht bestanden), Verweis (depends_on oder {ref:…} ohne Ziel), Termini (ein Absatz widerspricht einer Regel der Sprachinstitution) und Zahlen (zwei Blöcke lesen dieselbe Datei auf dieselbe Weise und melden für denselben Oracle-Schlüssel verschiedene Werte). Der Rückgabewert ist 0 nur ohne Befund. Ist LWgrammar nicht erreichbar, steht das als Befund Termini im Bericht; mit --ohne-termini entfällt diese Prüfung ausdrücklich. Die Prüfung über Pakete verschiedener Peers und über den Sinn eines Terminus in mehreren Notebooks ist noch nicht in Betrieb.

6 Token wechseln

openssl rand -hex 24 > ~/.config/famulus/token && chmod 600 ~/.config/famulus/token

Der Dienst liest die Datei bei jeder Anfrage; das neue Token gilt ohne Neustart. Danach brauchen alle Peers und Browser, die das alte Token kannten, das neue. Ein Token gehört in keine Datei, die weitergegeben wird, und in kein Protokoll. Der Dienst entfernt token= aus seinen Zugriffsprotokollen.