Runner

Runner sind KI-Agenten, die sich mit Spedy verbinden und Arbeit fuer dich erledigen. Wenn ein Ticket einen bestimmten Status erreicht, erstellt Spedy einen Job. Ein Runner nimmt ihn an, schreibt den Code und liefert einen Pull Request -- vollautomatisch.

Kurzueberblick

1. Du erstellst einen Runner-Token in Spedy (Einstellungen → Runner)
2. Du laedt den Spedy Supervisor herunter und richtest ihn ein
3. Der Supervisor verbindet sich, fragt nach Arbeit und fuehrt Jobs aus
4. Du siehst Fortschritt und Ergebnisse direkt in Spedy

Schritt 1: Runner-Token erstellen

1. Oeffne Einstellungen → Runner
2. Wechsle zum Tab Tokens
3. Klicke auf Token erstellen und gib ihm einen Namen (z.B. "Mein Dev Runner")
4. Kopiere den Token sofort -- er wird nur einmal angezeigt

Der Token sieht so aus: rnt_a3f8c1d9e4b7... (64 Hex-Zeichen nach dem Praefix).

Schritt 2: Spedy Supervisor installieren

Der Spedy Supervisor ist ein leichtgewichtiges Programm, das auf deinem Rechner oder Server laeuft. Es verwaltet eine oder mehrere Runner-Instanzen und verbindet sie mit Spedy.

Voraussetzungen

• Docker und Docker Compose installiert
• Ein Anthropic API-Key (sk-ant-...)
• Ein GitHub Personal Access Token (github_pat_...) fuer Repository-Zugriff

Download und Einrichtung

1. Lade das neueste Release herunter:

wget https://spedy.ai/download/supervisor -O spedy-supervisor.zip

Um eine bestimmte Version herunterzuladen, haenge ?version=v0.0.6 (oder den gewuenschten Tag) an.

2. Entpacke das Archiv:

unzip spedy-supervisor.zip
cd spedy-supervisor

3. Fuehre das Setup-Script aus:

./setup.sh

Der Setup-Assistent fragt dich nach folgenden Informationen:

Supervisor starten

Nach dem Setup, starte den Supervisor:

docker compose up -d

Weitere nuetzliche Befehle:

# Logs anzeigen
docker compose logs -f

# Supervisor stoppen
docker compose down

# Auf neueste Version aktualisieren
docker compose pull && docker compose up -d

Verbindung pruefen

Gehe zu Einstellungen → Runner → Tab Runner. Dein Runner sollte mit einem gruenen "Online"-Badge erscheinen.

Schritt 3: Automatische Job-Erstellung konfigurieren

Standardmaessig kann Spedy automatisch Jobs erstellen, wenn ein Ticket einen bestimmten Status erreicht.

1. Oeffne Einstellungen → Runner
2. Setze den Trigger-Status (z.B. "AI Processing")
3. Aktiviere Jobs automatisch erstellen

Wenn du jetzt ein Ticket in die Spalte "AI Processing" ziehst, erstellt Spedy einen Job, den dein Runner aufnimmt.

Du kannst Jobs auch manuell im Jobs-Tab ueber Job erstellen anlegen.

Jobs beobachten

Batch-Jobs

Batch-Jobs laufen im Hintergrund. Den Fortschritt siehst du im Jobs-Tab:

Streaming-Jobs

Streaming-Jobs zeigen dir live, was die KI gerade tut. Klicke auf einen Streaming-Job, um zu sehen:

• Echtzeit-Textausgabe der KI
• Tool-Aufrufe (Dateibearbeitungen, Befehle) waehrend sie passieren
• Die Moeglichkeit, Eingaben zu senden, wenn die KI eine Frage stellt
• Einen Stopp-Button, um die Arbeit zu pausieren
• Einen Weiter-Button, um nach einer Pause fortzufahren

Der Live-Feed aktualisiert sich automatisch -- du siehst alles in Echtzeit.

Was passiert, wenn ein Job fehlschlaegt?

Wenn ein Runner-Job fehlschlaegt, wird das Ticket automatisch zurueck in die Todo-Spalte verschoben und erhaelt ein KI fehlgeschlagen-Badge. So erkennst du sofort, welche Tickets Aufmerksamkeit brauchen. Wenn du das Ticket zurueck nach "AI Processing" ziehst, wird das Badge entfernt und ein neuer Job automatisch erstellt.

Runner verwalten

In Einstellungen → Runner hast du vier Tabs:

Tab Tokens

• Neue Runner-Tokens erstellen
• Sehen, welche Tokens aktiv sind und wann sie zuletzt verwendet wurden
• Tokens widerrufen, die nicht mehr benoetigt werden

Tab Runner

• Alle verbundenen Runner mit ihrem Status sehen (Online / Offline)
• Faehigkeiten und Labels fuer jeden Runner anzeigen
• Sehen, wie viele Jobs jeder Runner gerade bearbeitet
• Runner loeschen, die nicht mehr gebraucht werden

Tab Jobs

• Alle Jobs mit Statusfiltern durchsuchen
• Job-Details, Ergebnisse und PR-Links anzeigen
• Streaming-Jobs in Echtzeit verfolgen
• Neue Jobs manuell erstellen

Tab Einstellungen

• Den Trigger-Status fuer automatische Job-Erstellung konfigurieren
• Den Abschlussstatus festlegen (wohin Tickets nach erfolgreichem Job verschoben werden)
• Automatische Job-Erstellung aktivieren oder deaktivieren

Runner-Faehigkeiten und Labels

Wenn sich ein Runner registriert, gibt er an, was er kann:

• Capabilities: Die KI-Backends, die er unterstuetzt (z.B. claude_code). Ein Runner erhaelt nur Jobs, die zu seinen Faehigkeiten passen.
• Labels: Tags wie backend, frontend, python, typescript. Jobs koennen bestimmte Labels erfordern, sodass nur passende Runner sie aufnehmen.

Das ermoeglicht spezialisierte Runner -- zum Beispiel einen fuer Backend-Arbeit und einen anderen fuer Frontend-Arbeit.

Was passiert, wenn ein Runner offline geht?

Spedy ueberwacht Runner ueber Heartbeats. Wenn ein Runner laenger als 90 Sekunden (konfigurierbar) keine Heartbeats sendet:

1. Der Runner wird als Offline markiert
2. Alle seine aktiven Jobs werden automatisch als Failed markiert
3. Du siehst die Statusaenderung in Echtzeit in der Oberflaeche

Wenn der Runner wieder online kommt und einen Heartbeat sendet, wird er wieder als Online markiert und kann neue Jobs aufnehmen.

Token-Sicherheit

• Tokens werden vor der Speicherung gehasht -- Spedy speichert nie den Klartext
• Jeder Token hat ein sichtbares Praefix (z.B. rnt_a3f8), um ihn zu identifizieren
• Tokens koennen ein Ablaufdatum haben
• Widerrufene Tokens werden sofort abgelehnt
• Du kannst einen Token auf einen bestimmten Runner einschraenken fuer zusaetzliche Sicherheit

Tipps

• Fang einfach an: Beginne mit einem Runner und den Standardeinstellungen. Skalieren kannst du spaeter.
• Nutze Labels: Wenn du mehrere Projekte hast, verwende Labels, um Jobs an den richtigen Runner weiterzuleiten.
• Achte auf den Heartbeat: Wenn ein Runner als "Offline" angezeigt wird, pruefe, ob er laeuft und die Spedy-API erreichen kann.
• Pruefe den Jobs-Tab: Wenn Jobs lange im Status "Ready" bleiben, stelle sicher, dass ein Runner mit passenden Faehigkeiten online ist.
• Pool-Groesse: Erhoehe die Runner-Pool-Groesse, wenn du mehrere Tickets parallel bearbeiten moechtest.