Zum Hauptinhalt springen

Terminal Executor

Der Terminal Executor startet einen lokalen stdio-MCP-Server mit dem Tool execute_terminal. CLYE AI kann damit Shell-Befehle auf der Maschine ausführen, auf der die CLI läuft – im Vordergrund oder Hintergrund, mit optionalem Arbeitsverzeichnis, Datei-Import aus AI Hub und expliziter Rückgabe erzeugter Dateien.

Er eignet sich für lokale Automatisierung, Build-Schritte, Dev-Server, Dateikonvertierung und Betriebssystem-Workflows. Die Ausführungs-Engine ist dieselbe wie bei terminal-run; der Executor stellt die Funktion als MCP-Tool für AI Hub bereit.

Start​

# MCP-Server direkt starten (stdio)
ai-hub-cli terminal-executor

# Mit AI Hub verbinden und registrieren
ai-hub-cli mcp ai-hub-cli terminal-executor

Wenn du den Executor für CLYE AI nutzt, starte immer den mcp-Wrapper. Nur so werden Tool-Aufrufe über AI Hub geroutet. Details zur Registrierung findest du unter MCP-Registrierung.

MCP-Tool: execute_terminal​

ParameterPflichtBeschreibung
commandJaAuszuführender Shell-Befehl. Unter Linux und macOS wird er über /bin/sh -c ausgeführt, unter Windows über cmd /C.
is_backgroundNeinStartet den Befehl im Hintergrund und gibt sofort eine Prozess-ID zurück (z. B. bg_1). Hintergrundprozesse laufen unabhängig vom MCP-Kontext weiter.
working_directoryNeinArbeitsverzeichnis für den Befehl. Ohne Angabe wird das aktuelle Verzeichnis der CLI verwendet.
filesNeinDateien vor der Ausführung aus AI Hub herunterladen. Jeder Eintrag enthält file_ref (z. B. /f/<hash>) und dest_path (z. B. /tmp/beispiel.pdf). Schema wie bei execute_python.
output_file_pathsNeinExplizite Pfade erzeugter Dateien. Nur hier aufgeführte Dateien werden als Resource Links an CLYE AI zurückgegeben. Dateien, die der Befehl erzeugt, aber nicht auflistet, werden nicht automatisch übermittelt.

Beispiel: Befehl im Vordergrund​

ai-hub-cli mcp ai-hub-cli terminal-executor

Typischer Tool-Aufruf über MCP:

{
  "command": "ls -la",
  "working_directory": "/pfad/zum/projekt"
}

Beispiel: Hintergrundprozess​

{
  "command": "npm run dev",
  "is_background": true,
  "working_directory": "/pfad/zum/projekt"
}

Die Antwort enthält eine Prozess-ID wie bg_1 sowie den gestarteten Befehl. Der Prozess wird intern verwaltet und nach Beendigung automatisch aus der Prozessliste entfernt.

Beispiel: Dateien aus AI Hub und Ausgabe zurückgeben​

{
  "command": "convert /tmp/eingabe.png /tmp/ausgabe.pdf",
  "files": [
    {
      "file_ref": "/f/abc123",
      "dest_path": "/tmp/eingabe.png"
    }
  ],
  "output_file_paths": ["/tmp/ausgabe.pdf"]
}

Direkter CLI-Wrapper: terminal-run​

Für Smoke-Tests, Shell-Skripte und lokales Debugging ohne MCP-Client:

ai-hub-cli terminal-run "echo hello"
ai-hub-cli terminal-run --background "npm run dev"
ai-hub-cli terminal-run --working-dir /pfad/zum/repo "ls -la"
FlagBeschreibung
--backgroundStartet den Prozess im Hintergrund und gibt eine lokale Prozess-ID aus.
--working-dirSetzt das Arbeitsverzeichnis für den Befehl.

Mehr Details: python-run und terminal-run.

Umgebung und Runtime​

  • Shell: Unix-Systeme nutzen /bin/sh, Windows cmd.
  • Python-Pfad: Die Terminal-Umgebung erweitert die Python-Tool-Umgebung um schreibbare PYTHONUSERBASE- und PIP_CACHE_DIR-Verzeichnisse sowie ein erweitertes PATH für user-installierte Binaries.
  • OCR: Im Standard-Docker-Image sind OCR-Tools wie Tesseract verfügbar (inkl. Sprachpakete für Deutsch und Englisch).
  • Vordergrund-Ausführung: Befehle im Vordergrund respektieren MCP-Abbrüche; bei Cancellation wird der Prozess beendet.
  • Hintergrund-Ausführung: Hintergrundprozesse werden ohne Request-Kontext gestartet und laufen nach dem Tool-Aufruf weiter.

Verwandte Executors​

CommandToolsEinsatz
terminal-executorexecute_terminalNur Shell-Befehle als eigener MCP-Server.
combined-executorexecute_python, execute_terminalBeide Toolsets in einem Server; Standard im Docker-Image.
sandboxexecute_python, execute_terminalEingebetteter Combined Executor mit Workspace-Persistenz über AI Hub.

Übersicht aller Executors: Lokale MCP-Executors.

Sicherheit​

Terminal-Befehle werden lokal auf der Maschine ausgeführt, auf der die CLI läuft. Das Tool ist als destruktiv und open-world markiert. Starte den Executor nur in vertrauenswürdigen Umgebungen.

Für zusätzliche Isolation nutze Sandbox. Weitere Hinweise: CLYE CLI Sicherheit.

Inhalt