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.12 (siehe
.python-version). - Zugriff auf einen Server mit aktivem SSH/SFTP.
Installation
- Virtuelle Umgebung erstellen:
python3.12 -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 SSH-Sitzung auf (Standardport 22). SFTP wird bei der ersten Übertragung geöffnet./disconnect— beendet die aktive Verbindung./help— listet verfügbare Befehle./status— zeigt Agenten-, Provider-, Modell- und Streaming-Status sowie den Zustand des Prompt-Cachings, das Turn-Limit und jeden konfigurierten MCP-Server mit Zustand und Anzahl der Tools./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-AuslastungLade /tmp/script.sh nach /home/ubuntu/bin/script.sh hoch
Der Assistent nutzt die aktive SSH-Sitzung für Befehle. Dateiübertragungen öffnen SFTP bei Bedarf und protokollieren jede Aktion ausführlich. Relative Remote-Pfade werden relativ zum Startverzeichnis der SFTP-Sitzung (normalerweise das Home-Verzeichnis) aufgelöst; fehlende Verzeichnisse werden dort angelegt.
Agent und /connect laufen in einem Hintergrund-Worker, sodass die TUI währenddessen bedienbar bleibt; eine weitere Eingabe vor Abschluss der laufenden Anfrage wird mit einem Hinweis im Gesprächspanel abgewiesen.
Konfiguration
-
conf/app_config.jsonenthä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.conflegt Provider, Tools und Timeouts fest. Nutzeconf/agent.conf.exampleals Ausgangsbasis. OpenAI unterstütztchat_completions(Standard) undresponses; gemeinsamemax_tokens- und Reasoning-Werte werden für den gewählten Endpoint normalisiert. Nutze Responses für GPT-5.x Function Tools mit aktivem Reasoning. Optionalesstatefulkannprevious_response_idwiederverwenden, aberreasoningContentbehält noch keine vollständige Multi-Turn-Kontinuität.OPENAI_API_KEYbleibt in der Umgebung. Das Beispiel nutztgpt-6.1-sol, Responses,reasoning_effort: mediumundmax_tokens: 32768(effektivmax_output_tokens); die reale Konfiguration nutzt65536. Bedrock bleibt bei8192, der Remote- Timeout bei900Sekunden undremote_command.max_output_chars: 120000.
Für LM Studiolms server startausführen; für CerebrasCEREBRAS_API_KEYexportieren. Mistral AI nutztMISTRAL_API_KEY,provider: mistral, standardmäßigreasoning_effort: highundmax_tokens: 16184(mistral-medium-3.5). Google Gemini nutztGEMINI_API_KEY(oderGOOGLE_API_KEY, oderapi_key_env),provider: geminiundgemini-3.8-flashmittemperature: 0.3undmax_tokens: 16384(gesendet alsmax_output_tokens); weitereparamsgehen anGenerateContentConfig,client_argsan dengoogle-genai-Client (vertexai: truefür Vertex AI). -
Prompt-Caching: Jeder Provider-Block akzeptiert ein optionales Objekt
cache(enabled,strategy,ttl,system_prompt_ttl,tools_ttl,cache_key), das auf Strands'CacheConfigabgebildet wird. Bedrock nutzt standardmäßigenabled: truemitstrategy: "auto"(Cache-Points nur bei Claude-Modell-IDs). OpenAI und Mistral nutzen standardmäßigenabled: trueund senden einen stabilenprompt_cache_key, der aus Konfigurationspfad undmodel_idabgeleitet wird; legecache_keyfest oder setze ihn auffalse, um ihn abzuschalten. LM Studio bleibt deaktiviert, bis es explizit aktiviert wird; Ollama, Cerebras und Gemini ignorieren den Block mit einer Warnung im Log (Gemini cacht Präfixe implizit, und gemeldete gecachte Tokens erscheinen trotzdem in/status)./statuszeigt, ob Caching aktiv ist, sowie die gecachten gegenüber den gesamten Eingabe-Tokens des letzten Turns. -
Turn-Limit:
agent.max_turns(Standard25) begrenzt die Turns, jeweils ein Modellaufruf plus die angeforderten Tools, die der Agent für eine Anweisung verwenden darf. Beim Erreichen stoppt der Agent sauber, das Fenster ergänzt eine Warnung mit dem Hinweis auf eine engere Anweisung, und ein WARNING wird protokolliert;nulloder0deaktiviert das Limit,/statuszeigt den aktiven Wert. -
Tools:
tools.defaultlegt fest, welche Strands Agents Tools registriert werden (das Beispiel aktiviertshell,file_read,file_writeundsleep; fehlt der Schlüssel, sind alle aktiv).remote_ssh_command,remote_sftp_transferundlocal_datetimestehen immer bereit. Dastimeout_secondsvonremote_ssh_command(Standard900) begrenzt die Gesamtlaufzeit des Befehls, nicht die Wartezeit zwischen Ausgaben; für lange Aufgaben den Agenten bitten, einen höheren Wert zu übergeben. -
MCP-Server: Der Block
mcpdeklariert die Transportestdio,sseundstreamable_http(MCP 2.x); HTTP-Transporte berücksichtigenheaders. Die Server starten parallel, undtimeout_seconds(Standard30) begrenzt sowohl den Start jedes Servers als auch seine Anfragen, sodass ein hängender Server die TUI nicht mehr blockiert. Ein Server, der nicht startet, wird mit einer Warnung im Gesprächspanel übersprungen;/statuslistet jeden Server mit Zustand und Anzahl der Tools.
Fehlerbehebung
- Farb-/Darstellungsprobleme:
TERMprüfen und ggf. aufxterm-256colorwechseln. - Assistent reagiert nicht:
conf/agent.conf, Zugangsdaten undlogs/app.logkontrollieren. - "Keine aktive SSH-Verbindung": Vor Remote-Aktionen
/connectausführen. - SFTP-Fehler nach erfolgreichem
/connect: Die Remote-Shell kann Banner in nicht-interaktiven Sitzungen ausgeben (z. B.pyfigletin~/.bashrc). Dekorative Ausgabe nur interaktiv erlauben oderSubsystem sftp internal-sftpauf dem Server setzen. - Zugangsdaten in Logs:
/connect-Passwörter werden inlogs/app.logals***maskiert. - Der Agent hat mit einer Turn-Limit-Warnung gestoppt: Die Anweisung brauchte mehr als
agent.max_turnsTurns, oder das Modell forderte in einer Schleife Tools an (z. B. mit leeren Argumenten). Teile die Anfrage in kleinere Anweisungen auf; braucht die Aufgabe wirklich mehr Schritte, erhöheagent.max_turnsinconf/agent.conf. - Ein MCP-Server ist nicht gestartet: Das Konversationsfenster zeigt beim Start eine Warnung, und
/statuslistet jeden konfigurierten MCP-Server mit Zustand und Anzahl der Tools. Die Meldung nennt die Ursache (Befehl nicht gefunden, Prozess vorzeitig beendet, HTTP 401/403/404, keine Verbindung, keine Antwort innerhalb vontimeout_seconds, nicht gesetzte Umgebungsvariablen) und was inconf/agent.confzu korrigieren ist. Der Agent startet trotzdem ohne die Werkzeuge dieses Servers;logs/app.logenthält die vollständige Ablaufverfolgung.
Weitere Ressourcen
- Contributor-Handbuch: zentrale Richtlinien zu Dokumentation, Lokalisierung und Release-Zyklen.
- Produktüberblick: Architektur, Technologie-Stack und operative Verantwortlichkeiten.