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](#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](/hilfe/workspace-admin#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 |