Installation

Ein Rechner, ein Cluster, nur Notebooks

Veröffentlichungsdatum

23. September 2026

In einem Satz

./install.sh richtet Famulus Notebook in seinem eigenen Ordner ein; Optionen entscheiden, ob der Rechner Blöcke selbst ausführt, als Dienst läuft und von anderen Rechnern erreichbar ist.

Famulus Notebook ist ein eigener Arbeitsbereich, famulus-notebook. Auf den Rechnern des Clusters liegt er unter ~/ai-mac-studio/development/famulus-notebook/. Er enthält Parser, Viewer, Server, Kommandozeile und diese Seiten. Die Installation schreibt nichts außerhalb dieses Ordners, außer dem Token und, auf Wunsch, einem launchd-Job.

1 Drei Fälle

Ein Rechner ohne Sammlungen und ohne Query-Pipeline, zum Beispiel ein Laptop. Er zeigt Notebooks an, rendert sie und nimmt Anmerkungen auf. Partituren spielt er nicht selbst; ein Block mit engine: <peer> läuft auf dem genannten Rechner (Verknüpfung). Blöcke aus duckdb-read, auch gegen eine Sammlung eines Peers, und aus Tabellen-, Bericht- oder JSON-Artefakten rechnet er selbst. Ein Oracle kann er dabei nicht vergleichen; ein solcher Block endet mit einem Fehler, der das sagt.

./install.sh
.venv/bin/famulus-notebook serve

Der Rechner, an dem PDAI-1 hängt. Er führt Blöcke selbst aus und braucht dazu ai-agent-orchestrator und ai-query als Nachbarordner (../ai-agent-orchestrator, ../../pdai/agents/ai-query).

./install.sh --run --launchd

Der Rechner mit Sammlungen soll von den anderen Rechnern aus erreichbar sein. Dazu braucht er ein Token und eine Adresse außerhalb von 127.0.0.1.

./install.sh --run --token --launchd --host 0.0.0.0

Die anderen Rechner tragen ihn danach als Peer ein. Wer nur über Tailscale Serve und den Plattform-Proxy zugreift, braucht --host nicht: beide erreichen den Dienst über 127.0.0.1.

2 Optionen

Option	Wirkung
ohne Option	Python-Umgebung (`uv`, Python 3.14), Viewer-Build, Quarto-Site
`--run`	zusätzlich Blockausführung; bricht ab, wenn die Nachbarordner fehlen
`--launchd`	Dienst `com.ai-platform.famulus-notebook`, Port 5118, prüft danach `nc -z 127.0.0.1 5118`
`--token`	legt `~/.config/famulus/token` an (24 Zufallsbytes, hexadezimal, Modus 0600), wenn die Datei fehlt
`--host ADRESSE`	der Dienst hört auf dieser Adresse; ohne Token verweigert das Skript jede andere Adresse als `127.0.0.1`
`--trust-tailnet`	Anfragen aus 100.64.0.0/10 brauchen kein Token

Das Skript prüft vorab, ob uv, npm und pandoc vorhanden sind. Fehlt quarto, bleibt die Site ungerendert, und /docs bleibt leer; das Skript sagt das.

3 Umgebungsvariablen

Jeder Pfad lässt sich durch eine Umgebungsvariable ersetzen. So läuft dieselbe Installation auf Rechnern mit anderer Ordnerordnung.

Variable	Standard	Bedeutung
`FAMULUS_NOTEBOOK_PORT`	5118	Port des Dienstes
`FAMULUS_JOURNAL`	`~/Documents/Famulus/Notebooks`	eigene Notebooks, darunter `journal` und `goldens`
`FAMULUS_NOTEBOOKS`	leer	weitere Ordner mit Projekten, getrennt durch `:`
`FAMULUS_PEERS`	`~/.config/famulus/peers.yaml`	Verknüpfungen
`FAMULUS_TOKEN_FILE`	`~/.config/famulus/token`	Token dieses Dienstes
`FAMULUS_TOKEN`	leer	Token direkt, statt aus der Datei
`FAMULUS_PEER_TOKEN`	leer	Token für Peers, deren Eintrag kein `token_env` nennt
`FAMULUS_TRUST_TAILNET`	`0`	`1` lässt das Tailnet ohne Token zu
`PDAI_COLLECTIONS`	`/Volumes/PDAI-1/pdai-collections`	Wurzel der Sammlungen
`AIQUERY_URL`	`http://127.0.0.1:5113`	ai-query, für Anmerkungen und Lernen
`LEKTORAT_URL`	`http://127.0.0.1:5114`	ai-lektorat, für die Überarbeitung von Fließtext

4 Nach der Installation

nc -z 127.0.0.1 5118; echo $?          # 0: der Port antwortet
curl -s http://127.0.0.1:5118/api/health

/api/health nennt die Zahl der gefundenen Notebooks, ob der Viewer gebaut ist und ob die Blockausführung verfügbar ist. Erst diese Antwort zeigt, dass der Dienst läuft; ein geladener launchd-Job allein zeigt es nicht.