Benutzerhandbuch — Shell Sentinel

Überblick

Shell Sentinel ist eine Terminal-Anwendung, die eine persistente SSH/SFTP-Sitzung zu einem entfernten Server aufbaut und einen KI-Assistenten bereitstellt, der natürliche Sprache in überprüfbare Administrationsaufgaben umsetzt.

Voraussetzungen

Terminal mit Farbfähigkeit (empfohlen xterm-256color).
Python 3.10 oder neuer.
Zugriff auf einen Server mit aktivem SSH/SFTP.

Installation

Virtuelle Umgebung erstellen:

python3 -m venv .venv
source .venv/bin/activate

Abhängigkeiten installieren:

make install

Sprachkonfiguration

Die Anwendung liest SMART_AI_SYS_ADMIN_LOCALE. Ist die Variable nicht gesetzt, wird das Systemlocale verwendet (Standard: Englisch).

export SMART_AI_SYS_ADMIN_LOCALE=de   # Deutsch
export SMART_AI_SYS_ADMIN_LOCALE=en   # Englisch
export SMART_AI_SYS_ADMIN_LOCALE=es   # Spanisch

Start der Anwendung

make run

Beim Start erscheint ein retro-inspirierter Begrüßungsbildschirm, der sich nach fünf Sekunden schließt oder sobald eine Taste gedrückt wird.

Oberfläche

Gesprächspanel: zeigt Antworten des Assistenten im Markdown-Format.
Eingabefeld: mehrzeilig; Standard-Tastenkombination zum Senden ist Ctrl+S.
Fußzeile: informiert über den SSH-Status sowie Provider-/Modellinformationen.

Wichtige Befehle

Alle Befehle stehen auf Englisch, Spanisch und Deutsch zur Verfügung.

/connect <host> <user> <password|key_path> [Port] — baut die Remote-Sitzung auf (Standardport 22).
/disconnect — beendet die aktive Verbindung.
/help — listet verfügbare Befehle.
/status — zeigt Agenten-, Provider- und Modellstatus.
/exit — öffnet den Bestätigungsdialog zum Beenden.

Arbeiten mit dem Assistenten

Formuliere Anweisungen in natürlicher Sprache. Wenn es kein Slash-Befehl ist, verarbeitet der Strands-Agent die Eingabe. Beispiele:

Zeige die Prozesse mit der höchsten CPU-Auslastung
Lade /tmp/script.sh nach /home/ubuntu/bin/script.sh hoch

Der Assistent nutzt die aktive SSH/SFTP-Sitzung für Befehle und Dateiübertragungen und protokolliert jede Aktion ausführlich.

Konfiguration

conf/app_config.json enthält Styles, Texte und Shortcuts als Platzhalter wie {{ui.output_panel.title}}, die pro Locale aufgelöst werden.
Übersetzungen befinden sich unter conf/locales/<sprache>/strings.json. Neue Texte werden im Code mit _("schlüssel") referenziert und für jede Sprache gepflegt.
conf/agent.conf legt Provider, Tools und Timeouts fest.
Nutze conf/agent.conf.example als Ausgangsbasis.
Für LM Studio den lokalen Server mit lms server start starten; für Cerebras CEREBRAS_API_KEY exportieren oder api_key_env setzen (SDK mit SSE-Unterstützung).
Mit remote_command.max_output_chars begrenzt du die Anzahl der Zeichen, die der Agent erhält.

Fehlerbehebung

Farb-/Darstellungsprobleme: TERM prüfen und ggf. auf xterm-256color wechseln.
Assistent reagiert nicht: conf/agent.conf, Zugangsdaten und logs/app.log kontrollieren.
"Keine aktive SSH-Verbindung": Vor Remote-Aktionen /connect ausführen.

Weitere Ressourcen

Contributor-Handbuch: zentrale Richtlinien zu Dokumentation, Lokalisierung und Release-Zyklen.
Produktüberblick: Architektur, Technologie-Stack und operative Verantwortlichkeiten.