Runabot CLI#

Mit dem Kommandozeilenwerkzeug runabot verwalten Sie Workloads, Addons und Kontonutzung im Terminal oder per Skript. Nutzen Sie es interaktiv, automatisieren Sie Aufgaben in CI/CD-Pipelines oder lassen Sie Ihren KI-Agenten Runabot-Ressourcen in Ihrem Auftrag verwalten.

1. Download & Installation#

Vorkompilierte Binärdateien für Linux, macOS und Windows (jeweils für amd64 und arm64) stehen direkt auf der Downloads-Seite zur Verfügung.

Schnellinstallation#

# Benutzerinstallation (installiert nach ~/.local/bin/):
curl -fsSL https://int.runa.bot/downloads/install.sh | sh

# Globale Systeminstallation (installiert nach /usr/local/bin/):
curl -fsSL https://int.runa.bot/downloads/install.sh | sudo sh

Alternativ können Sie die Datei manuell von der Downloads-Seite herunterladen und ausführbar machen:

chmod +x runabot
sudo mv runabot /usr/local/bin/

2. Authentifizierung#

Anmelden#

Verwenden Sie im lokalen Terminal und bei einer Remote-Verbindung denselben Befehl:

runabot auth login --base-url https://int.runa.bot

Die CLI öffnet nach Möglichkeit Ihren Browser und zeigt eine Bestätigungs-URL sowie einen Benutzercode an. Öffnen Sie die URL auf einem beliebigen Gerät im Browser, geben Sie bei Aufforderung den Code ein und bestätigen Sie die Anmeldung. Die CLI schließt die Anmeldung automatisch ab und speichert Ihre Sitzungsdaten in der lokalen Konfiguration.

Auf der Zustimmungsseite wählen Sie, welche Berechtigungen Sie der CLI geben. Erteilen Sie nur den benötigten Zugriff. Für Änderungen an Ausgabengrenzen ist eine zusätzliche, optionale Berechtigung erforderlich.

Sie können den CLI-Zugriff jederzeit in den Benutzereinstellungen unter Authorized Applications widerrufen. Wählen Sie die CLI-Anwendung und klicken Sie auf Revoke.

Direkte Token-Anmeldung#

runabot auth login --token "<ihr-zugriffstoken>"

Agenten- & CI/CD-Modus (Umgebungsvariablen)#

Für automatisierte Coding-Agenten oder CI/CD-Pipelines können Zugriffstoken und Basis-URL über Umgebungsvariablen übergeben werden:

export RUNABOT_BASE_URL="https://int.runa.bot"
export RUNABOT_TOKEN="<ihr-zugriffstoken>"

Anmeldestatus prüfen#

runabot auth whoami

3. Befehlsübersicht#

Version & Build-Metadaten#

# Detaillierte Versions- und Build-Informationen (JSON, YAML, Tabelle oder Text) ausgeben
runabot version
runabot version -o json
runabot version -o table

# Nur die Versionsnummer ausgeben
runabot version --short
runabot --version

Ausgabeformatierung#

Befehle liefern standardmäßig strukturiertes JSON für Skripte. Für eine übersichtliche Konsolentabelle übergeben Sie -o table oder --output table:

runabot addon list -o table
runabot bot list -o table

Netzwerkverbrauch des Accounts#

# Aktueller UTC-Monat bis jetzt
runabot account network-usage

# Gewählter Zeitraum (höchstens 31 Tage)
runabot account network-usage --start 2026-09-01T00:00:00Z --end 2026-09-02T00:00:00Z

Der Befehl liefert die gesendeten und empfangenen Bytes des Accounts, stündliche Werte je Workload, den Zeitpunkt der letzten Messung und einen Status. Angegebene Zeitgrenzen werden auf volle UTC-Stunden gerundet. Standardmäßig gilt der aktuelle UTC-Monat bis jetzt. Die Werte enthalten internen Datenverkehr und unterstützende Dienste. Sie sind weder Abrechnungswerte noch eindeutiger Internetverkehr.

Bot-Verwaltung#

Deklarative Bereitstellung (apply)#

Bots und Addons deklarativ mittels YAML-Manifesten erstellen oder aktualisieren:

# Manifest (einzelnes oder mehrere Dokumente) anwenden
runabot apply -f workload.yaml

# Direkt über Standardeingabe übergeben (z. B. durch KI-Agenten generiert)
cat <<EOF | runabot apply -f -
apiVersion: runabot.runabot.de/v1
kind: BotInstance
metadata:
  name: clawdius-dev
spec:
  displayName: "Clawdius Developer Agent"
  chartName: openclaw
---
apiVersion: runabot.runabot.de/v1
kind: Addon
metadata:
  name: main-db
spec:
  sourceRef: cnpg
  displayName: "PostgreSQL Datenbank"
  parameters:
    storage_size: "10Gi"
EOF

Addon-Verwaltung#

Die Mindestwerte für Addon-Ressourcen stehen im Katalog der Addon-Quelle. Der Katalog zeigt außerdem, ob CPU, Arbeitsspeicher, Datenträger oder Netzwerk geändert werden dürfen. Als fest gekennzeichnete Ressourcen können nicht angepasst werden.

Git-Proxy-Verwaltung#

Git Proxy bietet unter runabot addon git-proxy eine ressourcenorientierte CLI. Jeder Befehl wählt die installierte Addon-Instanz ausdrücklich aus. Beim Lesen von Zugangsdaten werden nur Metadaten zurückgegeben; Geheimnisse werden nur beim Erstellen, Aktualisieren oder Rotieren angenommen.

Aktualisierungen und Löschungen benötigen die aktuelle --version. Mit --secret-action preserve, replace oder clear ist die Behandlung von Geheimnissen eindeutig. Mutationen unterstützen außerdem die globalen Flags --idempotency-key und --request-id.

Beachten Sie, dass access check den Repository-Pfad erwartet, wie ihn der Git Proxy sieht: <proxy-path-prefix>/<upstream-repository-path> (z. B. github_runabot/run-a-bot/mcpproxy-go). Bei exakten Pfadregeln wird direkt gegen das Pfadmuster der Regel geprüft; hängen Sie kein .git an, es sei denn, Ihr Regel-Muster enthält explizit .git.

MCPProxy-Verwaltung#

MCPProxy bietet unter runabot addon mcpproxy eine direkte Verwaltungs-CLI. Jeder Befehl nennt ausdrücklich die installierte Addon-Instanz. Die CLI verwaltet Upstream-Server, Tool-Freigaben, schreibgeschützte Geheimnisse, Zugriffsprofile, begrenzte Tokens und Bot-Zuweisungen. Lesebefehle geben niemals Header-, Umgebungs- oder Geheimniswerte zurück; neue und rotierte Tokenwerte werden einmalig ausgegeben.

runabot addon mcpproxy upstream create mcpproxy-u1a1 docs \
  --protocol streamable-http --url https://mcp.example.com/mcp
runabot addon mcpproxy profile create mcpproxy-u1a1 research \
  --upstream docs --tool docs=search
runabot addon mcpproxy assign mcpproxy-u1a1 research bot-u1b1
runabot addon mcpproxy access effective mcpproxy-u1a1 bot-u1b1

SSH-JumpHost-Verwaltung#

Der SSH JumpHost bietet unter runabot addon ssh eine ressourcenorientierte CLI. Sie akzeptiert ausschließlich öffentliche OpenSSH-Schlüssel. Runabot nimmt keine privaten Schlüssel an, erzeugt oder speichert sie nicht und gibt sie nicht zurück.

Zum Ersetzen oder Entfernen eines Schlüssels ist dessen aktuelle --version erforderlich. Beim Hinzufügen oder Ersetzen muss genau eines von --public-key oder --public-key-file angegeben werden. Vergleichen Sie vor einem unbeaufsichtigten Verbindungsaufbau einen Fingerprint aus connection mit dem Schlüssel, den der zurückgegebene knownHostsCommand ermittelt.

runabot addon ssh key add ssh-u1a1 \
  --name automation --public-key-file ~/.ssh/id_ed25519.pub
runabot addon ssh assignment assign ssh-u1a1 bot-u1b1
runabot addon ssh reachable ssh-u1a1
runabot addon ssh connection ssh-u1a1 bot-u1b1

Sicherungen & Wiederherstellung#

Administration#

4. Idempotenz & Ausfallsichere Wiederholungen#

Autonome Agenten können bei Netzwerk-Timeouts fehlgeschlagene oder unterbrochene Operationen gefahrlos mit einem Idempotenz-Schlüssel wiederholen, ohne doppelte Ressourcen zu erzeugen:

# Sichere Wiederholung mit deterministischem Schlüssel
runabot bot create --name worker-agent --chart openclaw --idempotency-key "task-20260825-worker" --wait
runabot addon create openobserve --idempotency-key "task-20260825-logs"

Wiederholen Sie die Erstellung mit demselben Schlüssel, um doppelte Workloads zu vermeiden. Die Antwort kann die Anfrage lediglich bestätigen. Ermitteln Sie mit bot list oder addon list den erzeugten Namen und Namespace, bevor Sie weitere Befehle ausführen.

5. Konfiguration & Umgebung#

Das CLI speichert Cluster, angemeldete Benutzer und benannte Kontexte in einer YAML-Datei:

• Linux / macOS: ~/.config/runabot/config.yaml (oder $XDG_CONFIG_HOME/runabot/config.yaml)
• Windows: %APPDATA%\runabot\config.yaml

runabot auth contexts listet die Kontexte auf. Mit --context <name> wählen Sie einen Kontext für einen Befehl; standardmäßig wird der aktuelle verwendet.

Sie können den Konfigurationspfad mit dem Flag --config oder der Umgebungsvariablen RUNABOT_CONFIG anpassen:

# Benutzerdefinierte Konfigurationsdatei verwenden
runabot --config ./staging.yaml bot list

# Oder über Umgebungsvariable
export RUNABOT_CONFIG=/pfad/zu/mein-cluster.yaml

Unterstützte Variablen & Flags#

6. Integration mit lokalen Coding-Agenten#

Die Runabot CLI liefert standardmäßig strukturiertes JSON, was die Integration in LLM-Coding-Agenten (Claude Code, Cursor, Codex, OpenClaw, Hermes) erleichtert:

# Beispiel 1: Parameter-Schema vor dem Erstellen eines Addons prüfen
runabot addon source describe olla -o json

# Beispiel 2: Bot synchron erstellen und auf Betriebsbereitschaft warten
runabot bot create --name data-pipeline --chart openclaw --wait --timeout 3m

# Beispiel 3: Laufzeitereignisse bei Fehlersuche abfragen
runabot bot events data-pipeline

Abrechnung und Kauflimits#

runabot account quota ist schreibgeschützt und enthält aktuelle Zuweisungen, Ausgabengrenzen, Traffic-Guthaben, die Änderungshistorie und die monatliche Zahlungsprojektion.

Änderungen erfordern die optionale OAuth-Berechtigung purchase_limits:

runabot account set-limits --allocation-weekly-eur 5 --traffic-weekly-eur 1

Die Berechtigung ist auf der Zustimmungsseite standardmäßig nicht ausgewählt. Ohne sie kann die CLI Abrechnungsdaten lesen, Änderungen werden jedoch von der API abgelehnt.