Doku

Erste Schritte

Was Whiskers ist, Anmelden und der Aufbau der Oberfläche.

Was ist Whiskers?

Whiskers ist deine zentrale Web-Steuerung für eine Flotte von Docker-Hosts: Container, Images, Netzwerke, Datenbanken, Firewall, Nginx, systemd, SSL, Metriken und Logs: alles an einem Ort. Dieselben Fähigkeiten stehen optional einer KI über einen abgesicherten MCP-Endpunkt zur Verfügung (siehe Kapitel KI-Agent und MCP-Server).

Designziel ist SSH-schlüsselfreier Betrieb: Hosts werden über ein privates Mesh mit gegenseitigem TLS (mTLS) angesprochen, sodass kein dauerhafter Privatschlüssel herumliegt, den jemand stehlen könnte.

Anmelden

Beim ersten Start führt dich der Setup-Wizard im Browser durch die Einrichtung — Admin-Konto anlegen, Schlüssel einmalig sichern, ganz ohne Konfigurationsdatei. Danach meldest du dich wahlweise lokal (E-Mail + Passwort) oder per Single Sign-On (Google/OIDC) an. Nur freigegebene E-Mail-Adressen erhalten Zugang. Deine Rolle bestimmt, was du darfst:

• Viewer: alles ansehen, keine Änderungen.
• Operator: Container starten/stoppen/neustarten, Befehle ausführen.
• Admin: alles inkl. Server anlegen, Guardrails, Einstellungen, Löschen.

Der Aufbau der Oberfläche

Die Oberfläche besteht aus vier Bereichen:

1. Sidebar (links): die Navigation, nach Themen gruppiert (Übersicht, Deployment, Infrastruktur, Automatisierung) plus Einstellungen und Hilfe.
2. Topbar (oben): die Glocke (Benachrichtigungen), das Paletten-Icon (Theme wechseln) und dein Profil/Abmelden.
3. Inhaltsbereich: die jeweils geöffnete Seite.
4. KI-Widget (unten rechts): der schwebende Agent-Chat, auf jeder Seite verfügbar (wenn der Agent aktiviert ist).

Dashboard & Übersicht

Server-Karten, Container-Gruppen, Status und Schnellaktionen.

Server- und Container-Karten

Das Dashboard zeigt jeden Server mit seinen Containern. Container sind gruppiert nach Standalone, Compose-Projekt und Telemetry. Pro Container siehst du Name, Image, Status (running/exited/created), Zustand (gesund/ungesund), CPU- und RAM-Last sowie den Statustext.

Klick auf einen Container-Namen öffnet die Detailansicht; das ▶/■-Symbol startet bzw. stoppt ihn direkt, der Mülleimer entfernt ihn (nur mit ausreichender Rolle).

Schnell zur richtigen Stelle

Viele Stellen verlinken direkt: Klickst du z. B. eine Image-Update-Benachrichtigung an, landest du sofort auf der Detailseite des betroffenen Containers: auch wenn er auf einem anderen Server läuft.

Container verwalten

Detailansicht: Statistiken, Logs, Terminal, Umgebung, Datenbank, CVEs.

Die Detailansicht

Die Container-Detailseite bündelt alles in Tabs:

• Übersicht: ID, Image, Ports, Labels, Erstellzeit.
• Statistiken: Live-CPU/RAM/Netz/Disk plus historische Verlaufs-Charts (1 h bis 7 Tage).
• Logs: Live-Logfenster mit Filter.
• Zustand: Health-Historie (Status, Exit-Code).
• Terminal: interaktive Shell im Container (wo unterstützt).
• Umgebungsvariablen: laufende Variablen (sensible maskiert) und, bei Compose: die .env-Datei bearbeitbar.
• Datenbank: nur bei DB-Containern: Query-Builder, Tabellen-Browser, Backup, Migration/Seed.
• CVEs: die Sicherheitslücken im Image.

Aktionen

Oben rechts: Starten / Stoppen / Neustarten (Operator) und Entfernen (Admin). Jede Aktion wird im Audit-Protokoll festgehalten.

Umgebungsvariablen ändern

Im Tab Umgebungsvariablen kannst du bei Compose-Projekten die .env bearbeiten. Sensible Keys (Passwörter, Tokens) bleiben maskiert: zum Überschreiben auf das Stift-Symbol. Achtung: Speichern startet den Container neu (kurze Downtime).

CVE-Monitor

Schwachstellen-Scan der Images, Schweregrad, Fixes und Alter.

Wie der Scan funktioniert

Der CVE-Monitor scannt Container-Images (Trivy) und das Host-OS auf bekannte Schwachstellen. Jede CVE erscheint einmal: alle betroffenen Container/Server stehen dahinter, statt dieselbe CVE dutzendfach zu listen.

Pro Finding siehst du Schweregrad (Critical/High/Medium/Low), die CVE-ID (verlinkt), das betroffene Paket, die installierte Version und: falls vorhanden: die Fix-Version.

Alter & Scan-Intervall

Zu jeder CVE wird das Alter geführt: sowohl seit wann sie in deiner Umgebung auftaucht als auch das offizielle Veröffentlichungsdatum. So erkennst du Altlasten.

Der Scan läuft nicht bei jedem Seitenaufruf, sondern im Hintergrund (Standard alle 12 h) und lässt sich manuell anstoßen. Benachrichtigt wird nur bei neuen CVEs.

Fixes einspielen

„Fix available" heißt: Es gibt eine gepatchte Paketversion. Bei Images bedeutet das meist ein Image-Update (neueres Tag ziehen + Container neu erstellen): siehe Deployment. Beachte: Manchmal ist der Fix upstream noch nicht in ein lauffähiges Image eingeflossen.

Log-Suche & Alerts

Container-Logs durchsuchen und Alarm-Regeln einrichten.

Logs durchsuchen

Auf der Seite Log-Suche gibst du einen Suchbegriff (oder mit Schalter Regex einen regulären Ausdruck) ein und schränkst optional auf einen Container ein. Praktisch zur schnellen Fehlersuche über Container hinweg.

Alarm-Regeln

Unter Alert-Regeln legst du Muster an, auf die Whiskers das Log laufend prüft. Jede Regel hat Name, Muster (Text oder Regex), Container (oder Alle) und Severity (error/critical). Schlägt eine Regel an, kommt eine Benachrichtigung und optional ein AI-Trigger (siehe AI-Trigger), der den Agenten automatisch reagieren lässt.

Tipp: Halte Muster eng genug, um Rauschen zu vermeiden, aber so, dass echte Service-Exceptions und Crashes weiter zuverlässig erfasst werden.

Infrastruktur & Server

Server hinzufügen, Cloud-Steuerung, Netzwerke und Backups.

Wie Whiskers Server erreicht

Whiskers spricht jeden Host über die Docker-API an: entweder lokal, über einen SSH-Tunnel oder über TCP mit gegenseitigem TLS (mTLS). Für Host-Befehle (Firewall, Nginx, systemd …) startet es einen kurzlebigen, privilegierten Helfer-Container, der per nsenter in den Host springt: ohne dauerhaften SSH-Schlüssel.

Einen Server hinzufügen

Unter Infrastruktur → Server → Hinzufügen legst du einen Host an:

1. Name und Verbindungstyp (Local / SSH / TCP+mTLS).
2. Verbindungsdaten (Host, Port, ggf. Zertifikate/Schlüssel).
3. Optional Cloud-Provider (Hetzner/Hostinger) + API-Key für Out-of-Band-Steuerung.

Beim Speichern baut Whiskers die Verbindung gleich auf und testet sie (kurzes Timeout): Klappt es, schließt der Dialog mit der Container-Zahl; klappt es nicht, bleibt er offen und zeigt den Fehler: so wird kein toter Server unbemerkt gespeichert. Ein nicht erreichbarer Host wird im Dashboard als „nicht erreichbar" markiert, statt die ganze Übersicht leer zu machen.

Onboarding: SSH-frei werden

Für einen frischen Host bringt dich „Speichern & Onboarden" (bei Verbindungstyp SSH) in einem Rutsch ins Mesh: Über eine einmalige SSH-Bootstrap-Verbindung: wahlweise mit SSH-Key oder Root-Passwort: installiert Whiskers (falls nötig) Docker, bringt Tailscale hoch (der Login-Link erscheint direkt in der App), deployt Telemetrie + den mTLS-Proxy und stellt den Host auf TCP+mTLS um.

Danach ist der Server SSH-frei und die Bootstrap-Zugangsdaten werden automatisch entfernt: das Passwort aus dem Speicher, der SSH-Key von der Platte. Es bleibt kein stehender Zugang übrig.

Cloud, Netzwerke, Backups

• Cloud: Power on/off, Reboot, Snapshots und Metriken direkt beim Provider, selbst wenn SSH/Docker mal nicht erreichbar ist. Funktioniert sobald pro Server Provider + API-Key gesetzt sind.
• Netzwerke: Docker-Netzwerke anlegen, Container verbinden/trennen.
• Backups: Volume-Backups als komprimierte Archive; vor riskanten Aktionen empfohlen.

Kubernetes (k3s)

Cluster verbinden, Pods im Dashboard, Whiskers per Helm betreiben.

Cluster verbinden

Unter Infrastruktur > Server > Hinzufügen legst du einen Server vom Typ Kubernetes an und fügst die kubeconfig ein — sie wird verschlüsselt im Vault gespeichert, nie im Klartext auf der Platte. Ausgelegt auf k3s, funktioniert mit jedem erreichbaren Cluster.

Pods im Dashboard

Pods erscheinen wie Container im Dashboard, gruppiert nach ihrem Besitzer (Deployment/StatefulSet/DaemonSet), mit Status und Logs. Als Aktionen stehen Skalieren und Rollout-Neustart bereit — bewusst ehrlich: Was Kubernetes selbst heilt, verspricht Whiskers nicht doppelt.

Whiskers auf Kubernetes

Andersherum läuft Whiskers selbst per Helm-Chart auf deinem Cluster (oci://ghcr.io/lupusmalusdeviant/charts/whiskers) — Single-Replica by design, non-root, restricted PodSecurity.

Deployment

Bereitstellen, Compose-Editor und App Store.

Container bereitstellen

Unter Deployment → Bereitstellen startest du einen neuen Container: Image, Name, Ports, Volumes, Umgebungsvariablen und Restart-Policy: wie ein geführtes docker run.

Compose-Editor & App Store

• Compose Editor: docker-compose.yml direkt im Browser bearbeiten und deployen.
• App Store: kuratierte Vorlagen (Redis, Nginx, Ghost …) als Startpunkt; Platzhalter wie {PROJECT}/{PORT} werden beim Deploy ersetzt.

Git-Deploy, Registries & Updates

Vom Repository zum laufenden Stack — und per Klick wieder zurück.

Git-Deployments

Unter Deployment > Git-Deploy verbindest du ein Git-Repository mit einem Zielserver: Whiskers klont bzw. pullt das Repo dort und bringt es per Docker Compose hoch. Der Zugriffs-Token liegt nur im Vault. Zusammen mit der Webhook-Aktion git-deploy wird daraus Push-to-Deploy direkt aus deiner CI.

Private Registries

In Einstellungen > Registries hinterlegst du private Container-Registries (GHCR, Harbor …); die Zugangsdaten liegen im Vault. Image-Pulls authentifizieren sich automatisch, sobald der Registry-Host der Image-Referenz passt.

Image-Updates & Rollback

Whiskers erkennt neuere Image-Versionen und aktualisiert Container auf Wunsch automatisch (opt-in, auch als geplante Aufgabe). Vor jedem Update wird die alte Konfiguration samt Image-Stand als Snapshot festgehalten — über den Rollback-Knopf auf dem Dashboard kehrst du mit einem Klick zurück.

Der KI-Agent

LLM-Anbindung, Chat-Widget, Vision und der Wechsel Berater → handelnder Agent.

Einrichten

Unter Automatisierung → Agent verbindest du ein LLM: Anbieter (OpenAI/Anthropic/Gemini …), API-Key und Modell. Beim Einfügen des Keys testet Whiskers die Verbindung und füllt die Modellliste automatisch.

Berater vs. handelnder Agent

Das schwebende Chat-Widget (unten rechts) ist auf der gesamten Seite verfügbar. Es kennt die aktuell geöffnete Seite (liest den angezeigten Inhalt) und kann auf Wunsch einen Screenshot ans Vision-Modell mitschicken.

• Deaktiviert/Berater: der Agent erklärt und schlägt vor, führt aber nichts aus.
• Aktiviert/handelnd: der Agent darf Werkzeuge benutzen (Container neu starten, Befehle ausführen …): immer begrenzt durch die Guardrails und ggf. Freigaben.

Das Widget bedienen

Das Fenster ist verschiebbar (am Kopf ziehen) und größenveränderbar (untere Ecke). Eingabe mit Enter senden, Shift+Enter für eine neue Zeile. Antworten können Live-Widgets enthalten: z. B. ein CPU/RAM-Chart oder eine Status-Karte direkt im Chat.

Guardrails

Code-erzwungene Sicherheits-Policy für den Agenten.

Was Guardrails tun

Guardrails sind eine unumgängliche Policy, die am Werkzeug-Boundary durchgesetzt wird, nicht bloß im Prompt. Selbst wenn das Modell etwas Verbotenes versucht, wird es im Code geblockt. Nur Admins können Guardrails ändern.

Presets & Werkzeug-Modi

Du legst mehrere Presets an und schaltest das aktive um. Pro Werkzeug wählst du den Modus:

• Erlauben: frei nutzbar.
• Bestätigen: erzeugt eine Freigabe (siehe nächstes Kapitel), bevor es läuft.
• Sperren: komplett verboten.

Freigaben (Human-in-the-Loop)

Heikle Agent-Aktionen genehmigen oder ablehnen.

Wie Freigaben funktionieren

Wenn der Agent eine Aktion auslöst, die laut Guardrail eine Bestätigung braucht, entsteht eine Freigabe: Was, von welchem Agenten/Akteur, welches Werkzeug, mit welchen Parametern plus optionalem Diff. Du bekommst eine Push-Benachrichtigung an die Glocke (und ggf. Mattermost/Matrix).

Genehmigen / Ablehnen

Auf der Seite Freigaben klickst du Genehmigen oder Ablehnen. Genehmigst du, läuft die Aktion weiter; lehnst du ab, bricht der Agent sie sauber ab. Abgelaufene Anfragen verfallen automatisch.

Agent-History

Lückenlose Aufzeichnung jedes Werkzeug-Aufrufs.

MCP-Beobachtbarkeit

Die Agent-History protokolliert jeden Werkzeug-Aufruf: Werkzeug, Akteur/Key, Parameter (sensible Werte redigiert), Entscheidung (erlaubt/abgelehnt/bestätigt), Ergebnis bzw. Fehler, Dauer und Server. So ist jederzeit nachvollziehbar, was die KI getan hat.

Filtern & Details

Filtere nach Akteur, Werkzeug, Zeitraum oder nur Schreibzugriffe/Ablehnungen. Ein Klick öffnet die Detailansicht mit Parametern und Ergebnis. Aufbewahrung wie das Audit-Protokoll (90 Tage).

AI-Trigger

Den Agenten automatisch auf Ereignisse reagieren lassen.

Automatische Reaktionen

Ein AI-Trigger verbindet ein Ereignis (z. B. eine angeschlagene Log-Alarm-Regel oder ein ungesunder Container) mit einem autonomen Agent-Lauf. Du legst fest, wann er feuert und welche Anweisung der Agent dann bekommt.

Auch hier gilt: Der autonome Lauf ist durch Guardrails und Freigaben begrenzt: heikle Schritte landen weiterhin zur Bestätigung bei dir.

Geplante Aufgaben & Webhooks

Wiederkehrende Aktionen planen und Aktionen von außen anstoßen.

Geplante Aufgaben

Unter Automatisierung > Geplante Aufgaben planst du wiederkehrende Aktionen per Cron-Ausdruck: Container-Neustarts, Image-Updates, Selbst-Backups, Aufräum-Jobs und mehr. Jeder Lauf landet im Audit-Protokoll.

Eingehende Webhooks

Webhooks stoßen Aktionen von außen an, z. B. ein Redeploy aus der CI. Jeder Webhook hat ein Pflicht-Secret; Aufrufe müssen über den Raw-Body per HMAC-Signatur (X-Hub-Signature-256) signiert sein — kompatibel mit GitHub, GitLab und Gitea. Das Secret wird genau einmal angezeigt.

Backup & Wiederherstellung

Whiskers’ eigene Daten sichern und crash-sicher zurückspielen.

Selbst-Backup

Unter Einstellungen > Backup sichert Whiskers sein eigenes Datenverzeichnis (Server-Liste, Vault, Metriken, Schlüssel) als tar.gz — auf Wunsch verschlüsselt (AES-256-GCM, abgeleitet vom VAULT_KEY). Auch als geplante Aufgabe mit Aufbewahrungsregel. Davon getrennt gibt es weiterhin Volume-Backups für die Daten deiner Container.

Wiederherstellen

Ein Backup spielst du per Upload zurück: Whiskers validiert es, legt automatisch ein Pre-Restore-Backup an, wechselt in den Wartungsmodus und tauscht die Daten crash-sicher beim Neustart. Verschlüsselte Backups brauchen denselben VAULT_KEY.

Benachrichtigungen

Die Glocke, Kanäle und Deep-Links.

Die Glocke

Die Glocke oben rechts sammelt Ereignisse: Image-Updates, ungesunde/abgestürzte Container, neue CVEs, Log-Alarme, Freigaben, Metrik-Ausreißer u. v. m. Die Zahl zeigt Ungelesene; ein Klick öffnet die Liste und markiert alles als gelesen.

Kanäle & Deep-Links

Neben der In-App-Glocke kann Whiskers zusätzlich an Mattermost oder Matrix senden. Viele Benachrichtigungen sind klickbar und springen direkt zur richtigen Stelle: z. B. ein Image-Update direkt zum betroffenen Container.

Einstellungen

Bearbeitbare App-Einstellungen und Metrik-Alarme.

Einstellungen ändern

Unter Einstellungen passt du das Verhalten an: gruppiert nach Themen. Dazu gehören Metrik-Alarme: Schwellen für CPU/RAM, bei deren Überschreiten du benachrichtigt wirst. Einstellungen sind nur für Admins schreibbar.

MCP-Server (KI-Anbindung)

Externe KI-Clients wie Claude Code anbinden.

Was MCP ist

Whiskers stellt seine Fähigkeiten über das Model Context Protocol (MCP) bereit. Ein externer KI-Client (z. B. Claude Code) verbindet sich mit dem MCP-Endpunkt und kann dann: im Rahmen seiner Berechtigung: Container listen, Logs lesen, Befehle ausführen usw.

API-Keys & Berechtigungen

In den Einstellungen → MCP legst du API-Keys an. Jeder Key hat eine Stufe:

• Read: nur lesen (listen, inspizieren, Logs).
• Write: zusätzlich verändern (start/stop, deploy, Befehle).
• Admin: alles.

Alternativ schränkst du einen Key auf eine explizite Werkzeugliste ein. Jeder Aufruf landet in der Agent-History.

Topologie, Vergleichen, Audit & Health

Die übrigen Analyse- und Nachvollziehbarkeits-Werkzeuge.

Topologie

Übersicht → Topologie zeichnet ein Netzwerk-Diagramm: welche Container in welchen Docker-Netzwerken hängen. Gut, um Abhängigkeiten und Isolation zu sehen.

Vergleichen & Audit-Protokoll

• Vergleichen: stellt Konfigurationen/Zustände gegenüber, um Abweichungen zu finden.
• Audit-Protokoll: lückenlose Historie aller Benutzer-Aktionen (wer hat wann was gestartet/gestoppt/geändert). Ergänzt die Agent-History (KI-Aktionen).

Statusberichte (Health)

Übersicht → Statusberichte fasst den Gesundheitszustand der Flotte zusammen: ungesunde Container, Restart-Loops und auffällige Hosts.

Themes & Branding

Das Aussehen umstellen.

Theme wechseln

Über das Paletten-Icon oben rechts wählst du den Modus — Hell, Dunkel oder System (folgt dem Betriebssystem live) —, das Farbschema (Ember, Aurora, Ocean, Nebula, Rose) und die Sprache (Deutsch/Englisch). Die Wahl wird im Browser gespeichert. Das Logo in der Sidebar färbt sich passend zum aktiven Theme.

Übrigens: Genau diese fünf Themes kannst du auch hier auf der Website über das Paletten-Icon unten rechts ausprobieren.