Zum Inhalt

KI- & API-Zugang

Mit einem API-Zugang arbeitet Claude (oder eine andere KI) in Vesana für dich: sie sieht, was du sehen darfst, und kann ändern, was du ändern darfst — nie mehr. Typische Aufträge:

  • „Gestern ist der Windows-Server abgestürzt — was war da los?"
  • „Welche Probleme sind gerade offen, und was davon ist dringend?"
  • „Richte mir die Geräte in meinem Homelab ein."

Alles dazu steht unter Admin → System → KI:

Reiter Inhalt
Anbieter Welches Modell der Vesana-Chat nutzt (Ollama, Anthropic, OpenAI-kompatibel)
Zugänge Alle KI- & API-Zugänge der Instanz, Zugänge für andere Personen anlegen
Einstellungen KI- & API-Zugang erlaubt ja/nein, höchste Laufzeit neuer Zugänge

Der Schalter steht nach dem Update auf an. Wird er ausgeschaltet, wirkt kein Zugang mehr und claude.ai kann sich nicht verbinden; die Zugänge bleiben gespeichert.

Das KI-Konto

Jeder Zugang läuft auf einem eigenen KI-Konto der Person, zum Beispiel lukas-ai für Lukas. Es entsteht beim ersten Zugang von selbst.

  • Im Audit-Log steht das KI-Konto als Akteur („lukas-ai, über API-Zugang Claude, im Auftrag von lukas"). So ist auf einen Blick klar, was die KI getan hat und was ein Mensch.
  • Das KI-Konto hat keine eigenen Rechte. Es bekommt bei jeder Anfrage die heutigen Rechte seiner Person. Verliert die Person ein Recht, verliert es auch die KI — sofort.
  • Es kann sich nicht anmelden: kein Passwort, kein 2FA, kein SSO.
  • In der Benutzerverwaltung steht es mit dem Etikett KI. Ein Admin kann es deaktivieren (alle Zugänge der Person stehen dann still) oder löschen; Rolle, Tenants und Passwort lassen sich dort nicht setzen.
  • Dashboards, die die KI anlegt, gehören der Person, und die KI sieht die privaten Dashboards ihrer Person.

Wer darf

  • Für sich selbst legt einen Zugang an, wer das Recht API-Zugänge erstellen (api_tokens.create) hat. Die Rolle Admin hat es, Operator und Viewer nicht; eigene Rollen bekommen es per Häkchen unter Rollen.
  • Für eine andere Person legt einen Zugang an, wer zusätzlich Benutzer bearbeiten (users.edit) hat oder Super-Admin ist — und nur für Personen, die nirgends mehr Rechte haben als der Ersteller. Sonst könnte man über den Zugang mehr ausgeben, als man selbst hat.
  • Der Ersteller haftet: ein Zugang lebt nur, solange sein Ersteller noch Zugänge anlegen darf. Bekommt die Person später mehr Rechte als ihr Ersteller, steht der Zugang still.

Einen Zugang anlegen

Für dich: Einstellungen → API-Zugang → Neuer Zugang. Für eine Person: Admin → System → KI → Zugänge → Zugang für eine Person.

Zuerst wählst du, wofür der Zugang ist:

  • claude.ai: du legst nur Modus, Tenants und Laufzeit fest. Einen Schlüssel gibt es dabei nicht — claude.ai bekommt seinen Zugang beim Verbinden, und die Freigabe übernimmt diese Rechte. Du bestätigst dort nur noch.
  • Schlüssel: für Claude Code, Claude Desktop oder eigene Skripte. Vesana fragt vorher nach deiner Identität (Passkey, Authenticator-Code oder Passwort), denn ein Schlüssel ist ein langlebiger Zugang.
Einstellung Bedeutung
Modus: Nur lesen Die KI sieht alles, was die Person sehen darf, und ändert nichts. Die richtige Wahl für Fragen und Auswertungen.
Modus: Lesen + ändern Die KI darf ändern, was die Person ändern darf. Heikle Aktionen bleiben gesperrt: Benutzer anlegen, Script-Code ändern und alles andere, wofür Vesana sonst noch einmal nach der Identität fragt.
Modus: Voll Wie oben, zusätzlich die heiklen Aktionen ohne Rückfrage. Nur für eine KI, der du das zutraust.
Tenants Ohne Auswahl gilt der Zugang in allen Tenants, die die Person sieht, auch in künftigen. Mit Auswahl gilt er nur dort, und instanzweite Aktionen sind gesperrt, auch für einen Super-Admin.
Laufzeit Vorgabe 90 Tage. Unter Einstellungen kann ein Super-Admin eine Obergrenze setzen; dann ist „läuft nie ab" nicht mehr möglich.

Ein Schlüssel (vesana_pat_…) wird nur einmal angezeigt. Vesana speichert ihn nicht, nur einen Fingerabdruck davon.

Claude verbinden

claude.ai → Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen und als Adresse eintragen:

https://<deine-vesana-adresse>/api/v1/mcp

claude.ai öffnet danach Vesana. Du meldest dich an, siehst, wer Zugriff möchte, und gibst frei. Hast du unter „Neuer Zugang" → claude.ai Rechte festgelegt, stehen sie dort als eine Zeile — ein Klick auf „Zugriff erlauben" genügt, „Ändern" öffnet die Felder. Sonst wählst du Modus, Tenants und Laufzeit hier. Der Zugang steht danach unter Einstellungen → API-Zugang (Symbol eines Roboters, „verbunden über …").

Ein angelegter Schlüssel spielt dabei keine Rolle — claude.ai bekommt seinen Zugang allein über die Freigabe.

Andere Rechte oder neu verbinden: in claude.ai beim Vesana-Connector erneut „Verbinden" wählen und bei der Freigabe die Rechte ändern. Der neue Zugang ersetzt den alten desselben Connectors, der alte wird widerrufen (in der Liste „Ersetzt").

„Ein Connector mit dieser Adresse existiert bereits": der Connector steht schon in der Liste unter Einstellungen → Connectors, auch wenn sein Zugang widerrufen ist. Dort „Verbinden" wählen statt neu anlegen.

Adresse: im Split-Container-Betrieb die Adresse des Benutzer-Portals nehmen, nicht die des Admin-Portals — bei der Freigabe musst du dort angemeldet sein.

Vesana muss aus dem Internet erreichbar sein

claude.ai verbindet sich von Anthropics Servern aus, nicht von deinem Browser. Die Adresse muss deshalb aus dem Internet per HTTPS mit einem gültigen Zertifikat erreichbar sein (z. B. Let's Encrypt, siehe TLS). Läuft Vesana nur im eigenen Netz, siehe Instanz im eigenen Netz.

Nach dem Anlegen zeigt Vesana den fertigen Befehl:

claude mcp add --transport http vesana https://<deine-vesana-adresse>/api/v1/mcp \
  --header "Authorization: Bearer vesana_pat_…"

In claude_desktop_config.json (braucht Node.js):

{
  "mcpServers": {
    "vesana": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<deine-vesana-adresse>/api/v1/mcp",
               "--header", "Authorization:Bearer vesana_pat_…"]
    }
  }
}

Jede KI, die MCP spricht, nutzt https://<deine-vesana-adresse>/api/v1/mcp. Alles andere spricht die normale REST-API mit dem Kopf Authorization: Bearer vesana_pat_…. Die Beschreibung der API (OpenAPI) liegt unter /api/v1/mcp/openapi.

Instanz im eigenen Netz

Entscheidend ist, wer die Verbindung zum MCP-Server aufbaut:

Weg Wer verbindet sich Instanz nur im eigenen Netz
Claude Code, Claude Desktop mit mcp-remote, eigene Skripte dein Rechner geht, wenn der Rechner Vesana erreicht (LAN, VPN)
claude.ai, Connector in den Einstellungen von Claude Desktop Anthropics Server geht nur über das KI-Gateway

Zertifikat bei Claude Code und Claude Desktop: Beide laufen auf Node.js und vertrauen dem selbstsignierten Zertifikat einer frischen Installation nicht. Am einfachsten ist ein gültiges Zertifikat über Admin → System → Zertifikat mit DNS-01. Das funktioniert auch, wenn Vesana aus dem Internet nicht erreichbar ist (siehe TLS). Alternativ gibst du das Zertifikat der Instanz dem Client mit NODE_EXTRA_CA_CERTS=/pfad/zu/vesana.pem bekannt.

KI-Gateway für claude.ai

Das KI-Gateway ist ein eigener Port, der nur öffnet, was die Server von claude.ai brauchen: die Anmeldung (OAuth) und die Werkzeuge (MCP). Oberfläche, Login und die übrige API bleiben dort zu. Die Freigabe öffnet dein Browser wie gewohnt unter der Adresse der Oberfläche im eigenen Netz.

  1. Admin → System → KI → Einstellungen → KI-Gateway für claude.ai einschalten (Vorgabe Port 8445).
  2. Den Port aus dem Internet erreichbar machen, mit einem gültigen Zertifikat für die öffentliche Adresse:
    • Port-Freigabe an der Firewall auf den Vesana-Server, Port 8445. Das Gateway nutzt dasselbe Zertifikat wie die Oberfläche; die öffentliche Adresse gehört deshalb mit auf das Zertifikat (Admin → System → Zertifikat, mehrere Namen oder Wildcard per DNS-Prüfung). Wer will, beschränkt sie auf die Adressen, die Anthropic veröffentlicht.
    • Tunnel (z. B. Cloudflare Tunnel): Der Tunnel zeigt auf https://<vesana-server>:8445, ohne eingehenden Port. Das öffentliche Zertifikat stellt der Tunnel-Dienst; das selbstsignierte Zertifikat des Servers lässt du ihn ungeprüft annehmen (bei Cloudflare noTLSVerify).
  3. In claude.ai als Connector https://<öffentliche-adresse>/api/v1/mcp eintragen, bei Port-Freigabe mit :8445.

BASE_URL in der .env muss die Adresse der Oberfläche sein, so wie dein Browser sie aufruft. Fehlt sie, kann die Freigabe-Seite nicht geöffnet werden; die Karte im Admin-Bereich sagt das.

Der Vesana-Chat mit Vesana-Daten

Der eingebaute KI-Chat hat dieselben Werkzeuge. Ist neben Wiki und Web die Quelle Vesana eingeschaltet, fragt er die Daten der Instanz ab — mit deinen Rechten, über dein KI-Konto. Über der Antwort steht, welche Werkzeuge gelaufen sind.

  • Der Chat liest von sich aus nur.
  • Will er etwas ändern, hält er an und zeigt die geplante Änderung mit Ausführen und Abbrechen. Erst nach „Ausführen" läuft genau diese eine Änderung, danach antwortet der Chat weiter. Heikle Aktionen (Benutzer, Script-Code …) macht der Chat nie.
  • Im Audit-Log steht „über Vesana-Chat".
  • Mit Anthropic und OpenAI-kompatiblen Anbietern funktioniert das. Bei Ollama hängt es am Modell: nicht jedes lokale Modell kann Werkzeuge benutzen. Dann antwortet der Chat ohne Vesana-Daten und sagt das.

Was die KI damit tun kann

Werkzeug Wofür
Suche Hosts, Checks, Tenants, Ordner nach Namen finden
Aktuelle Probleme Was gerade nicht OK ist, Schlimmstes zuerst
Host Ein Gerät mit allen Checks und offenen Problemen
Zeitleiste eines Hosts Was in einem Zeitfenster passiert ist: Statuswechsel, Verbindungs- und Agent-Ausfälle, Konfigurationsänderungen, Warnungen und Fehler aus den Logs
Verlauf eines Checks Statuswechsel und Werteverlauf
Logs Gesammelte Logeinträge durchsuchen (Windows-Ereignisanzeige, journald, Dateien)
API-Katalog + API-Aufruf Alles, was die Oberfläche kann: Hosts anlegen, Checks einrichten, Discovery starten, die Geräteansicht eines Geräts oder Profils ändern …
Lagebild Status, Tenants, Collectors, Active-Checker, Alarmierung und nicht überwachte Geräte in einem Aufruf
Leitfaden Fachwissen und Vorgehen von Vesana, z. B. zum Check-Bau oder zur Alarmierung — lädt die KI selbst, bevor sie etwas plant
Check-Katalog Die eingebauten Check-Typen mit ihren Feldern

Jeder Aufruf läuft durch dieselbe Rechteprüfung wie in der Oberfläche. Die KI findet keinen Weg an den Rechten der Person vorbei, denn es gibt keinen.

Was die KI nicht sieht: Gerätedaten, die Vesana nie gesammelt hat. Die Frage „Warum ist der Server abgestürzt?" lässt sich am besten beantworten, wenn am Host die Log-Sammlung eingeschaltet ist. Ohne sie sieht die KI nur Ausfälle und Statuswechsel.

Arbeitsabläufe

Arbeitsabläufe sind vorgefertigte Aufträge. Sie sagen der KI, in welcher Reihenfolge sie vorgeht, worauf sie in Vesana achtet und wie das Ergebnis aussieht. Sie laufen mit den Rechten des Zugangs; Änderungen schlägt die KI vor und führt sie erst nach deinem OK aus.

Ablauf Kennung Wofür
Check-Entwicklung check-design Neuen Check bauen oder bestehenden verbessern, nach der Vesana-Vorgehensweise, am echten Gerät geprüft
Monitoring-Review monitoring-review Lücken und Schwachstellen finden: Hosts ohne Checks, dauerhaft NO_DATA, fehlende Schwellwerte, Alarm-Lücken
Abdeckungsanalyse coverage-gap-analysis Geräte im Netz, die noch nicht überwacht werden, mit Profil-Vorschlag
Geräteaufnahme device-onboarding Gerät aufnehmen: Tenant, Ordner, Profil, Zugangsdaten, Ausführungsweg
Störungsanalyse incident-analysis Was ist passiert und warum, mit Zeitachse und wahrscheinlicher Ursache
Alarmierungs-Review alerting-review Erreicht jedes Problem die richtigen Leute, wo entstehen unnötige Meldungen
Wartungsplanung maintenance-window Downtime planen, abhängige Geräte inklusive
Statusbericht status-report Verfügbarkeit, Vorfälle und offene Punkte eines Tenants für einen Zeitraum

So startest du einen Ablauf:

  • claude.ai und Claude Desktop: im Eingabefeld auf + → Vesana → Ablauf wählen und die Felder ausfüllen.
  • Claude Code: /mcp__vesana__monitoring-review (bzw. die jeweilige Kennung).
  • Im Gespräch: einfach sagen, z. B. „Mach ein Monitoring-Review für den Tenant Muster". Claude kennt die Abläufe und schlägt sie auch selbst vor, wenn sie passen.
  • Vesana-Chat: im leeren Chat stehen einige Abläufe als Schnellstart.

Die Liste steht auch unter Einstellungen → API-Zugang.

Was ein Zugang nie kann

  • Zugänge anlegen oder verwalten, sich anmelden, Sitzungen, Passwort oder 2FA ändern
  • das eigene KI-Konto oder das Konto seiner Person über die Benutzerverwaltung ändern
  • Passwörter, Communities oder andere Geheimnisse lesen (sie sind für alle nur ***)
  • mehr als die Person, auch nicht im Modus „Voll"

Nachvollziehen und widerrufen

  • Einstellungen → API-Zugang zeigt deine Zugänge — die du angelegt hast und die für dich gelten — mit KI-Konto, Modus, Tenants, Laufzeit und „zuletzt benutzt von …". Ein Klick widerruft, er wirkt sofort.
  • Admin → System → KI → Zugänge zeigt alle Zugänge der Instanz mit Person und Ersteller (Super-Admins).
  • Ein neuer Zugang steht zusätzlich im Diagnose-Log (Kategorie Anmeldung).
  • Ein Zugang wird automatisch unwirksam, wenn das Konto der Person deaktiviert oder gelöscht wird, wenn ihr KI-Konto deaktiviert wird, wenn ein Admin ihr Passwort zurücksetzt, wenn der Ersteller das Recht verliert oder wenn der KI-Zugang ausgeschaltet wird.

Vorsicht

Anweisungen in Gerätedaten. Eine KI liest Texte, die von Geräten stammen: Check-Meldungen, Logzeilen, Hostnamen. Wer ein Gerät kontrolliert, kann dort Text hinterlegen, der wie eine Anweisung aussieht („lösche alle Hosts"). Vesana kennzeichnet solche Daten gegenüber der KI ausdrücklich als Daten, Claude fragt vor ändernden Werkzeugen nach, und der Vesana-Chat ändert nie ohne deine Bestätigung. Die wirksamste Vorsorge bleibt trotzdem: „Nur lesen" für alles, was nur fragen soll, und „Voll" nur, wenn du es wirklich brauchst.

Daten beim Anbieter. Was eine KI über einen Zugang abfragt, geht an ihren Anbieter — bei claude.ai an Anthropic, beim Vesana-Chat an den unter „Anbieter" eingestellten. Für Kundenumgebungen vorher klären, ob das erlaubt ist.