bifroest/app/help/pages/plattform-admin.md

Für Plattform-Admins

Als Plattform-Admin richtest du die Plattform ein: Teams und Nutzer, Modelle, die Einstufung der Tools und angebundene Dienste. Du siehst Nutzung, Runs und Audit-Log über alle Workspaces.

Ersteinrichtung

Die Schritte 1 bis 3 braucht jede Plattform, der Rest ist optional. Zu jedem Schritt steht, woran du siehst, dass er geklappt hat. Manche Dienste muss der Betrieb vorher auf dem Server freigeben, etwa erlaubte Hosts oder den E-Mail-Versand. Meldet Bifröst „Host nicht erlaubt“, ist das der Grund.

1. Modell (Modelle und Zugänge)

1. Endpunkt mit Namen und Basis-URL anlegen (OpenAI-kompatible Responses API bzw. AI Gateway).
2. Am Endpunkt einen API-Key hinterlegen, für alle Teams oder je Team.
3. Modell mit Modell-ID, Bezeichnung, Kontextgröße und, für Kosten, Preisen anlegen. Das erste Modell wird Standard.
4. Verbindung testen.

Klappt, wenn eine Frage in einem Workspace eine Antwort bekommt.

2. Tools (Tools)

Nicht eingestufte Tools sind gesperrt. Die eingebauten stufst du mit Vorschläge übernehmen ein; Tools neuer MCP-Server einzeln (siehe Tools einstufen).

Klappt, wenn unter einer Antwort Tool-Schritte erscheinen und keine Meldung „nicht verfügbar“.

3. Teams und Nutzer (Teams, Nutzer)

Teams anlegen, Konten anlegen und den Teams zuordnen. Neue Nutzer bekommen ein Einmal-Passwort.

Klappt, wenn sich jemand anmelden und im eigenen Team einen Workspace anlegen kann.

4. Gedächtnis mit Munin (MCP-Server)

1. Server mit der URL von Munin anlegen, Art: Gedächtnis.
2. Tools abrufen, dann Empfehlung übernehmen: Lesen und Merken erlaubt, Löschen durch die KI gesperrt.
3. Workspace-Admins schalten Munin danach in ihrem Workspace mit dem Munin-Key ihres Projekts frei.

Klappt, wenn nach „Merk dir …“ im Chat ein Eintrag unter Gedächtnis des Workspace steht.

5. Pakete aus Hugin (Hugin)

1. Host von Hugin eintragen → „Hugin ist erreichbar“.
2. Unter Tools load_skill, read_skill_file und hugin_feedback einstufen, falls noch offen.
3. Workspace-Admins tragen danach den Integrations-Key ihres Tenants ein und wählen Pakete.

Klappt, wenn im Chat / die Befehle aus Hugin vorschlägt.

6. Dokumenten-Auslese (MCP-Server)

Nötig, damit Office-Dateien, PDFs und Bilder in abgeglichenen Ordnern lesbar werden; Textdateien gehen ohne.

1. Server anlegen, Art: Dokumenten-Auslese, Tools abrufen.
2. Auf der Seite des Servers unter Dokumenten-Auslese das Tool und seine Parameter für Inhalt (Base64) und Dateiname wählen.

Klappt, wenn eine PDF in einem abgeglichenen Ordner nach kurzer Zeit „lesbar“ ist.

7. Datenbanken (Datenbank-Treiber)

DB-Dienst für PostgreSQL oder Oracle mit URL und Schlüssel registrieren, Tools abrufen, einstufen. Workspace-Admins verbinden danach ihre Datenbanken selbst.

Klappt, wenn der Treiber „ok“ zeigt und eine Verbindung im Workspace beim Test „verbunden“ meldet.

8. Freigaben und Benachrichtigungen

• Unter Nutzer globale Approver bestimmen, falls Tools die Freigabestufe globaler Approver bekommen.
• E-Mails zu Freigaben verschickt Bifröst, sobald der Betrieb den Versand eingerichtet hat. Unter Benachrichtigungen siehst du, ob sie ankommen. Jede Person trägt ihre Adresse im Profil ein.

Danach können Teammitglieder Workspaces anlegen und einrichten (siehe Workspace startklar machen).

Für Vorführungen: aiw demo auf dem Server legt zwei Workspaces mit Beispiel-Repository, Datei, Dokumenten und Beispielfragen an (Team „demo“, Nutzer anna, ben, clara): „Demo: Bestellservice“ (Fachanwendung mit Bestelldaten und, wenn der PostgreSQL-DB-Dienst läuft, einer angebundenen Shop-Datenbank) und „Demo: MCP-Entwicklung“ (eigener MCP-Server mit Leitfaden und Aufruf-Log). aiw demo mcp legt nur eine an, --reset legt sie neu an. Dafür müssen lokale Git-Quellen erlaubt sein (AIW_GIT_ALLOW_LOCAL=true).

Teams und Speicherkontingent

Ein Team fasst Nutzer zusammen; Workspaces gehören immer zu einem Team. Nur Mitglieder eines Teams können darin Workspaces anlegen und zu Workspaces hinzugefügt werden.

Auf der Seite eines Teams siehst du dessen Workspaces und stellst je Workspace das Speicherkontingent für Dateien zur Analyse ein (Standard 500 MB). Teams ohne Workspaces lassen sich löschen.

Nutzer

• Anlegen: Neue Nutzer bekommen ein Einmal-Passwort, das nur einmal angezeigt wird. Gib es auf sicherem Weg weiter; beim ersten Login muss ein eigenes Passwort gesetzt werden.
• Passwort zurücksetzen: erzeugt ein neues Einmal-Passwort, beendet alle Sitzungen und entsperrt das Konto sofort. Nach 5 Fehlversuchen ist ein Konto sonst 15 Minuten gesperrt.
• Plattform-Admin: Diese Rolle sieht alles in der Administration. Vergib sie sparsam.
• Globaler Approver: entscheidet Anträge der Freigabestufe globaler Approver, auch ohne Mitglied des Workspace zu sein.

Mit der späteren Anbindung an Keycloak entfallen die Passwörter in der Plattform.

Modelle und Zugänge

Die Seite hat drei Schritte:

1. Endpunkte: die Basis-URL einer OpenAI-kompatiblen API, z. B. das AI Gateway.
2. API-Keys: je Endpunkt ein Key für alle Teams oder je Team. Keys werden verschlüsselt gespeichert und nur gekürzt angezeigt.
3. Modelle: je Modell:
   • Modellname, wie die API ihn erwartet, und ein Anzeigename.
   • Kontextgröße (Tokens): Davon hängt ab, wie viel Verlauf in eine Anfrage passt (höchstens 60 %). Trage den echten Wert des Modells ein.
   • Preise je 1 Mio. Tokens für Eingabe, Eingabe aus Cache und Ausgabe. Sie ergeben die Kosten in Nutzung und Kosten.
   • Modellklasse und ob das Modell Tools und Reasoning unterstützt.

Das erste Modell wird automatisch Standard. Workspaces können ein anderes freigegebenes Modell wählen. Modelle außer dem Standard und Endpunkte ohne Modelle lassen sich löschen.

Budgets und Inhaltsfilter (Guardrails) liegen im AI Gateway. Blockiert es eine Anfrage, zeigt die Antwort Vom AI Gateway blockiert.

Tools einstufen

Jedes Tool hat eine Risikoklasse:

Risikoklasse	Bedeutung	Vorschlag
read	Liest nur	erlaubt
write_internal	Wirkt nur in der Plattform, z. B. Commit auf den Chat-Branch, Plan, Gedächtnis	erlaubt
write_external	Wirkt in einem Fremdsystem, z. B. schreibende MCP-Tools	Freigabe nötig
destructive	Löscht oder richtet schwer Umkehrbares an	gesperrt

Je Tool legst du fest:

• Einstufung: erlaubt, Freigabe nötig oder gesperrt.
• Freigabestufe: Workspace (Admin oder Freigeber) oder globaler Approver.
• Vier-Augen-Prinzip: Die auslösende Person darf nicht selbst freigeben.

Neue Tools sind gesperrt, bis sie eingestuft sind, auch nach einem Update der Plattform. Vorschläge übernehmen stuft alle noch offenen Tools nach ihrer vorgeschlagenen Risikoklasse ein. Workspaces können deine Einstufung nur verschärfen, nie lockern.

Eingebaute Tools (Auswahl):

Tool	Zweck	Vorschlag
git_read_file, git_search, git_find_files, git_list_dir, git_log, git_show_commit, git_diff, git_blame	Repository lesen	read
commit_change	Commit auf den Branch des Chats (einzelne Änderungen oder Patch)	write_internal
merge_target	Ziel-Branch per Merge-Commit übernehmen, Konflikte lösen	write_internal
update_plan	Plan des Chats pflegen	write_internal
git_pr_comments	Review-Kommentare des Pull Requests lesen	read
data_list_tables, data_describe_table, data_query	Hochgeladene Dateien abfragen	read
docs_list, docs_search, docs_read	Abgeglichene Ordner auflisten, im Volltext durchsuchen, lesen	read
load_skill, read_skill_file	Skill aus Hugin laden, Hilfsdatei lesen (nur mit festgeschriebenem Skill)	read
hugin_feedback	Rückmeldung an Hugin zu einem Paket des Workspace (höchstens 3 je Antwort)	write_external

Die vollständige Liste mit Beschreibung steht unter Tools.

MCP-Server

MCP-Server binden externe Dienste mit ihren Werkzeugen an.

1. Unter MCP-Server den Server registrieren (die URL muss in der Freigabeliste des Betriebs stehen).
2. Tools abrufen: lädt die Werkzeuge des Servers.
3. Die Tools unter Tools einstufen. Für Gedächtnis-Server gibt es Empfehlung übernehmen; dabei wird forget gesperrt.
4. Workspace-Admins schalten den Server für ihren Workspace frei.

Ein MCP-Server der Art Gedächtnis (Munin) liefert zusätzlich eine Anleitung, die in den System-Prompt geht.

Dokumenten-Auslese: Ein zentraler Server der Art Dokumenten-Auslese liest Office-Dateien, PDF und Bilder aus abgeglichenen Ordnern aus. Nach Tools abrufen auf der Seite des Servers unter Dokumenten-Auslese das Tool wählen, den Parameter für den Dateiinhalt (Bifröst schickt ihn als Base64) und optional den Parameter für den Dateinamen. Die KI ruft dieses Tool nicht selbst auf; der Worker schickt neue und geänderte Dateien dorthin und speichert den Text. Ohne diesen Server bleiben solche Dateien „nicht lesbar“; Textdateien (Markdown, TXT, CSV …) liest Bifröst selbst. Grenzen: AIW_DOC_MAX_MB je Datei, AIW_DOC_MAX_FILES je Ordner, AIW_DOC_MAX_TEXT_KB Text je Datei, AIW_DOC_EXTRACT_TIMEOUT_SECONDS je Auslese.

Verbindungen der Workspaces: Workspace-Admins legen eigene Verbindungen an. Zu einer Adresse, die die Plattform schon nutzt, sind sie sofort aktiv. Zu einer neuen Adresse warten sie unter MCP-Server → Warten auf Freigabe; alle Plattform-Admins bekommen dazu eine E-Mail. Nach Freigeben ruft Bifröst die Tools ab. Gleiche Tools desselben Dienstes erkennt Bifröst am Fingerabdruck (URL, Tool-Name, Beschreibung, Schema) und übernimmt die Einstufung; eine neue Einstufung des Originals gilt für alle. Neue oder geänderte Tools bleiben gesperrt, bis sie unter Tools eingestuft sind.

Datenbanken: Unter Datenbank-Treiber je Datenbanktyp einen DB-Dienst (services/db-mcp, z. B. db-mcp-postgres, db-mcp-oracle) registrieren: Bezeichnung (so heißt der Typ im Formular der Workspaces), Kurzname, URL und Schlüssel des Dienstes. Der Schlüssel öffnet nur den Dienst, keine Datenbank. Dann Tools abrufen und die vier Tools einstufen (list_tables, describe_table, query, check_connection; Vorschlag read). Workspace-Admins legen damit ihre Datenbanken mit eigenen Zugangsdaten an; deren Tools haben die Einstufung des Treibers und erscheinen nicht einzeln unter Tools. Die Seite Datenbank-Treiber zeigt, welche Datenbanken welchen Treiber nutzen. AIW_DB_ALLOWED_HOSTS begrenzt zusätzlich die Datenbank-Hosts.

Hugin

Unter Hugin trägst du die Hugin-Instanz der Plattform ein (Adresse; der Host muss wie bei MCP-Servern freigegeben sein). Speichern und prüfen testet die Erreichbarkeit. Den Integrations-Key seines Tenants trägt jeder Workspace-Admin selbst ein, denn ein Workspace gehört einem Team, und Teams haben in Hugin eigene Tenants mit eigenen Paketen.

Die Tabelle Workspaces zeigt je Workspace, ob ein Zugang eingerichtet ist und ob er funktioniert, mit Tenant, Key-Name und Anzahl gewählter und festgeschriebener Pakete. Keys siehst du dort nicht. Ein Wechsel des Tenants steht im Audit-Log (hugin.tenant_changed).

Nutzung, Runs, Audit-Log, Benachrichtigungen

• Nutzung und Kosten: Tokens und Kosten je Team, Workspace, Modell, Nutzer oder Tag. Darunter die Rückmeldungen zu Antworten über alle Workspaces, mit CSV-Export.
• Runs: alle Antworten über alle Workspaces, filterbar nach Status. Hier fallen z. B. Fehler oder lange Wartezeiten auf.
• Audit-Log: alle Ereignisse mit Filtern und CSV-Export.
• Benachrichtigungen: Stand der E-Mail- und Webhook-Zustellung. Fehlgeschlagene Zustellungen werden bis zu fünfmal wiederholt.

Betrieb

Für den technischen Betrieb, also Deployment, Monitoring und Backup, gibt es eine eigene Dokumentation im Repository (README, Abschnitt Betrieb). Kurz:

• Prozesse: Web (aiw web) und Worker (aiw worker). Antworten entstehen im Worker; ohne laufenden Worker bleiben sie in wartet.
• Health-Checks: /live und /ready für Web und Worker.
• Metriken: /metrics im Prometheus-Format, mit Token geschützt. aiw_untrusted_signals_total zählt fremde Inhalte, die wie Anweisungen an eine KI aussehen (Ereignis untrusted_signal im Log); blockiert wird dabei nichts.
• Logs: Text oder JSON, mit Request-ID und Run-ID. Prompts, Antworten und Zugangsdaten stehen nie im Log. Die Fehler-ID auf einer Fehlerseite findet man im Log wieder.
• Backup: Die Datenbank wird zentral gesichert. aiw backup sichert zusätzlich hochgeladene Dateien; aiw restore und aiw check gehören dazu.

Wichtige Einstellungen (Umgebungsvariablen, Auswahl):

Variable	Bedeutung	Standard
AIW_PUBLIC_URL	Adresse der Plattform für Links in E-Mails und Pull Requests	leer
AIW_GIT_ALLOWED_HOSTS, AIW_DB_ALLOWED_HOSTS, AIW_MCP_ALLOWED_HOSTS	Erlaubte Hosts für Quellen und Dienste	leer
AIW_WORKSPACE_STORAGE_MB	Speicherkontingent je Workspace	500
AIW_UPLOAD_MAX_MB	Größte Datei je Upload	200
AIW_MAX_TOOL_ROUNDS, AIW_MAX_TOOL_ROUNDS_LIMIT	Tool-Schritte je Antwort (Standard und Obergrenze)	12, 40
AIW_HISTORY_MAX_TOKENS	Verlauf je Anfrage	60 000
AIW_APPROVAL_HOURS	Ablauf von Freigabeanträgen	24
AIW_PR_POLL_SECONDS	Abfrage offener Pull Requests	300
AIW_WORKSPACE_TRASH_DAYS	Aufbewahrung im Papierkorb	14
AIW_SMTP_*	E-Mail-Versand	leer
AIW_METRICS_TOKEN	Schutz für /metrics	leer (aus)
AIW_LOG_FORMAT, AIW_LOG_LEVEL	Log-Format und -Level	text, INFO