Runner

Runner sind KI-Agenten, die sich mit Spedy verbinden und Arbeit für 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.

Kurzüberblick

1. Du hinterlegst deinen Anthropic-API-Key in Spedy (Einstellungen → Runner → Secrets)
2. Du verbindest GitHub / Bitbucket (Einstellungen → Integrationen) — der Runner übernimmt den Token automatisch
3. Du erstellst einen Runner-Token in Spedy (Einstellungen → Runner)
4. Du lädt den Spedy Supervisor herunter und richtest ihn ein
5. Der Supervisor authentifiziert sich mit dem Token, holt seine Secrets von der Platform und fängt an, Jobs zu bearbeiten

Der Runner speichert Anthropic-Keys oder Git-Tokens nie auf der Festplatte — sie werden beim Start über GET /runners/bootstrap ausgeliefert.

Schritt 1: Anthropic-API-Key auf der Platform hinterlegen

Der Runner holt sich seinen Claude-Key beim Start aus Spedy — du legst ihn nicht mehr in lokale Config-Dateien.

1. Öffne Einstellungen → Runner
2. Wechsle in den Tab Secrets
3. Klicke auf Secret hinzufügen, wähle Anthropic (Claude) als Preset und füge deinen sk-ant-… Key ein
4. Speichern

Der Wert wird mit AES-256-GCM verschlüsselt gespeichert und nur in der /runners/bootstrap-Antwort an authentifizierte Runner entschlüsselt. Auch Admins können den Klartext nach dem Speichern nicht mehr lesen — zum Rotieren gibst du einfach einen neuen Wert ein.

Überspringe diesen Schritt, wenn du Lokales Claude (Max/Pro) statt des API-Keys verwenden willst. In dem Fall nutzt der Supervisor deine lokalen Claude-Credentials.

Schritt 2: Git anbinden (GitHub / Bitbucket)

Der Runner übernimmt deine bestehenden Git-Integrationen automatisch. Wenn du unter Einstellungen → Integrationen bereits GitHub oder Bitbucket verbunden hast, ist für den Runner nichts zu tun. Falls nicht, lege die Integration dort an — der Runner holt sich den Token beim nächsten Bootstrap.

GitHub-Integration: Berechtigungen

Der GitHub-Token hinter der Integration braucht folgende Berechtigungen, damit der Runner Repositories klonen, Branches erstellen und Pull Requests öffnen kann:

Empfehlung: Verwende einen feingranularen Personal Access Token oder die Spedy-GitHub-App, jeweils nur auf die Repositories beschränkt, auf die der Runner zugreifen soll.

Schritt 3: Runner-Token erstellen

1. Öffne Einstellungen → Runner
2. Im Tab Runner findest du den Bereich zur Token-Verwaltung
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 Präfix). Nach dem Erstellen zeigt Spedy dir das passende .env-Snippet zum Kopieren sowie eine Readiness-Checkliste (Anthropic-Key im Vault? Git-Integration aktiv?). Mit dem Kopieren-Button hast du das Snippet in einem Rutsch.

Schritt 4: Spedy Supervisor installieren

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

Voraussetzungen

• Docker und Docker Compose installiert
• Der Runner-Token aus Schritt 3. Optional ein Claude-Max-Abonnement, falls du OAuth-Modus statt des Platform-managed Anthropic-Keys nutzen willst.

Download und Einrichtung

1. Lade das neueste Release herunter:

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

Um eine bestimmte Version herunterzuladen, hänge ?version=v0.0.6 (oder den gewünschten Tag) an.

2. Entpacke das Archiv:

unzip spedy-supervisor.zip
cd spedy-supervisor

3. Führe das Setup-Script aus:

./setup.sh

Der Setup-Assistent fragt dich nach folgenden Informationen:

Der Wizard fragt den Anthropic-API-Key oder einen GitHub-/Bitbucket-Token nicht mehr ab — diese Werte kommen zur Runtime von der Platform. Auf der Review-Seite läuft ein Readiness-Check; fehlt ANTHROPIC_API_KEY im Vault, wird das Bundle nicht an die lokale CLI gesendet. So geht kein Runner online, der beim ersten Job scheitert.

OAuth-Modus (Claude Max)

Wenn du ein Claude Max-Abonnement hast, kannst du den Anthropic API-Key komplett weglassen. Der Supervisor unterstützt den OAuth-Modus, bei dem Runner sich über deine lokalen Claude-Credentials authentifizieren statt über einen API-Key.

So nutzt du den OAuth-Modus:

1. Führe claude einmal auf deinem Rechner aus, um das ~/.claude-Verzeichnis zu erstellen
2. Lass beim Setup das Feld Anthropic API Key leer
3. Das Setup-Script erkennt ~/.claude automatisch und konfiguriert den Volume-Mount

Im OAuth-Modus wird kein API-Key injiziert und kein Proxy gestartet — die Claude CLI im Runner-Container nutzt ihre eigenen Credentials. Der Supervisor mountet ~/.claude automatisch in jeden Runner-Container.

Supervisor starten

Nach dem Setup, starte den Supervisor:

docker compose up -d

Weitere nützliche Befehle:

# Logs anzeigen
docker compose logs -f

# Supervisor stoppen
docker compose down

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

Verbindung prüfen

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

Runner-Secrets verwalten

Unter Einstellungen → Runner → Secrets verwaltest du die Credentials, die der Runner beim Start abruft:

• Anthropic (Claude) API-Key — einziger offiziell unterstützter LLM-Provider heute.
• Custom Env-Vars — alles weitere, was deine Jobs brauchen (projektspezifische Flags, Build-Tokens, …). Wähle den Custom-Scope und vergib den Env-Var-Namen selbst.

GitHub- und Bitbucket-Tokens gehören nicht hierher — sie kommen aus Einstellungen → Integrationen und werden automatisch in das Runner-Bootstrap gemerged. MCP-Server-Credentials leben auf ihren eigenen Konfigurationen unter Einstellungen → MCP Servers.

So gelangen die Werte zum Runner

1. Du speicherst ein Secret. Der Wert wird mit AES-256-GCM verschlüsselt, bevor er in die Datenbank geht.
2. Der Runner authentifiziert sich mit seinem rnt_… Token gegen GET /runners/bootstrap.
3. Spedy merged deine Vault-Einträge mit den Tokens deiner aktiven Git-Integrationen, entschlüsselt die Werte und liefert das Bundle über TLS aus.
4. Der Runner hält die Werte nur im Speicher und injiziert sie beim Start als Environment-Variablen in den Job-Container. Beim Exit werden sie gescrubbt.

Der Runner holt das Bundle alle 15 Minuten neu — eine Rotation propagiert also ohne Supervisor-Restart.

Secret rotieren oder entfernen

• Rotieren: Klicke auf die Secret-Zeile → Bearbeiten → füge den neuen Wert ein. Der Rotations-Zeitstempel wird gesetzt.
• Entfernen: Klicke auf Löschen. Runner verlieren den Zugriff beim nächsten Bootstrap.
• Lokales Override: Steht ANTHROPIC_API_KEY in deiner lokalen .env, gewinnt dieser Wert über den Platform-Wert. Lösche die Zeile, um den Key vollständig von der Platform managen zu lassen.

Deine Keys, deine Verantwortung

Der Secrets-Tab blendet permanent einen Hinweis ein:

• Jeder Job läuft gegen deinen Anthropic-Key. Spedy cappt, proxyt oder subventioniert den Verbrauch nicht — die Kosten laufen direkt gegen dein Anthropic-Konto.
• Setze Budgets und Rate-Limits im Anthropic-Dashboard und Token-Budgets pro Job unter Runner-Teams. Agent-Loops können ohne Cap sechsstellige Cache-Read-Counts erreichen.
• Committe niemals Credentials, .env-Dateien oder Private Keys in Repositories, die der Runner anfasst. Der Agent liest den kompletten Arbeitsbaum als Kontext und kann committete Secrets in Logs, Commits oder PR-Beschreibungen echoen.

Migration für bestehende Runner

Wenn du bereits Runner verbunden hattest, zeigt Spedy oben auf Einstellungen → Runner ein Migrations-Banner mit exakt zwei Schritten:

1. Anthropic-API-Key hinterlegen unter Einstellungen → Runner → Secrets (Schritt 1 oben).
2. Supervisor einmalig neu starten, damit er den neuen Bootstrap-Flow übernimmt:

docker compose pull
docker compose up -d --force-recreate spedy-supervisor

Sobald der ANTHROPIC_API_KEY im Vault liegt, verschwindet das Banner automatisch. Alte ANTHROPIC_API_KEY / GITHUB_TOKEN / BITBUCKET_* Zeilen in deiner lokalen .env darfst du während der Umstellung stehen lassen — lokale Werte überschreiben die Platform, es geht also nichts kaputt. Entferne sie, sobald alles grün läuft.

Schritt 5: Runner-Teams konfigurieren

Runner-Teams sind der zentrale Weg, um zu konfigurieren, wie Runner Tickets bearbeiten. Jedes Team definiert seine eigenen Status-Zuordnungen, Pipeline-Stufen und Trigger-Verhalten.

Runner-Team erstellen

1. Öffne Einstellungen → Runner
2. Wechsle zum Tab Runner-Teams
3. Klicke auf Team erstellen
4. Wähle ein Pipeline-Preset als Ausgangspunkt:
   • Code Runner -- startet mit Planungs-, Coding- und Review-Stufen, erstellt PRs bei Code-Änderungen
   • Board Agent -- eine einzelne benutzerdefinierte Stufe mit Nur-Lese-Tools, geeignet für Recherche und Projekt-Interaktionen
   • Review Team -- zwei KI-Reviewer (Security + Quality) arbeiten parallel, ein Review Lead fasst zusammen und verifiziert
   • Full-Stack Team -- Backend- und Frontend-Agent arbeiten parallel, ein Integration Validator prüft die Zusammenarbeit
5. Konfiguriere Teamname, Beschreibung und Status-Zuordnungen
6. Passe die Pipeline-Stufen nach Bedarf an

Team-Status-Zuordnungen

Jedes Runner-Team hat seine eigene Status-Konfiguration:

• Arbeitsstatus -- der Status, in den Tickets verschoben werden, während das Team sie bearbeitet (z.B. "AI Processing")
• Abschlussstatus -- wohin Tickets nach einem erfolgreichen Job verschoben werden (z.B. "In Review")
• Fehlerstatus -- wohin Tickets verschoben werden, wenn ein Job fehlschlägt (pro Team konfigurierbar, kein fester Status)

@Mention-Trigger

Jedes Team kann ein Mention-Handle haben (z.B. @helper oder @codebot). Wenn ein Nutzer ein Team-Handle in einem Ticket-Kommentar @erwähnt, erstellt Spedy automatisch einen Job für dieses Team -- dies ist der BOARD_INTERACTION-Job-Typ.

Pro-Team-Fähigkeiten und Labels

Teams können Capabilities (z.B. claude_code) und erforderliche Labels (z.B. backend, frontend) angeben, um zu steuern, welche Runner ihre Jobs aufnehmen. Nur Runner, die den Fähigkeiten und Labels des Teams entsprechen, erhalten Jobs von diesem Team.

Pipeline-Stufen

Jedes Runner-Team hat eine Pipeline von Stufen, die definieren, wie ein Job ausgeführt wird. Stufen laufen der Reihe nach, und jede Stufe kann ihre eigene Konfiguration haben.

Stufentypen

Stufen-Konfiguration

Jede Pipeline-Stufe kann konfiguriert werden mit:

• System-Prompt -- die Anweisungen, denen die KI in dieser Stufe folgt
• Erlaubte Tools -- welche Tools die KI verwenden darf (z.B. Read, Edit, Write, Bash, Grep, Glob, WebSearch, WebFetch)
• Modellauswahl -- wähle das KI-Modell für diese Stufe:
  • Haiku 4.5 -- schnell und kosteneffizient
  • Sonnet 4.6 -- ausgewogene Leistung
  • Opus 4.7 -- stärkstes Reasoning (Standard für Planungs-Stufen)
  • Opus 4.6 -- vorherige Generation, weiterhin wählbar für Teams, die auf dessen spezifisches Verhalten angewiesen sind
• Rolle -- Planner (nur lesen) oder Executor (lesen/schreiben)
• Genehmigung erforderlich -- Toggle, um die Pipeline zu pausieren und auf menschliche Genehmigung zu warten, bevor diese Stufe ausgeführt wird
• Validierungsbefehle -- Shell-Befehle, die nach einer Coding-Stufe automatisch ausgeführt werden (z.B. npm run lint, npm test). Wenn ein Befehl fehlschlägt, wiederholt der Agent die Stufe und behebt das Problem automatisch. Maximale Wiederholungen sind konfigurierbar (0-10). Gefährliche Shell-Patterns (Semikola, Pipes, Backticks, Redirects) werden serverseitig blockiert.
• Skills -- wiederverwendbare Skill-Anweisungssets anhängen, um das Verhalten der Stufe zu ergänzen
• MCP-Server-Konfigurationen -- externe Tool-Server über das Model Context Protocol verbinden

Du kannst Stufen per Drag-and-Drop umordnen, einzelne Stufen aktivieren oder deaktivieren und die Pipeline auf die Preset-Standards zurücksetzen.

Standard-Pipeline

Die Standard-Code-Runner-Pipeline hat drei Stufen:

1. Planer (Opus 4.7) -- analysiert das Ticket und erstellt einen Plan
2. Implementieren (Sonnet 4.6) -- schreibt den Code basierend auf dem Plan
3. Review (Sonnet 4.6) -- prüft die Implementierung auf Korrektheit, Sicherheit und Qualität und behebt Probleme direkt

Skills

Skills sind wiederverwendbare Anweisungssets, die du an Pipeline-Stufen anhängen kannst. Sie bieten zusätzlichen Kontext, Richtlinien oder spezialisiertes Wissen für die KI.

Verwalte Skills unter Einstellungen → Skills. Jeder Skill hat:

• Einen Namen (Slug-Format, z.B. code-review-richtlinien)
• Eine Beschreibung für Trigger-Matching
• Einen Inhalt (die eigentlichen Anweisungen in Markdown)

Skills können auf Organisationsebene oder für ein bestimmtes Board erstellt werden. Hänge Skills an jede Pipeline-Stufe an, um zu ergänzen, was die KI weiß und wie sie sich in dieser Stufe verhält.

MCP-Server-Konfigurationen

MCP (Model Context Protocol)-Server-Konfigurationen ermöglichen es dir, externe Tool-Server zu verbinden, die Runner während der Pipeline-Ausführung nutzen können. Dies erweitert die Fähigkeiten des Runners über die eingebauten Tools hinaus.

Verwalte MCP-Server unter Einstellungen → MCP-Server. Jede Konfiguration beinhaltet:

• Eine Server-URL (für SSE/HTTP-Transport) oder einen Befehl (für STDIO-Transport)
• Optionale Authentifizierungs-Credentials
• Einen optionalen Filter für erlaubte Tools

MCP-Server-Konfigurationen können auf die Organisation oder ein bestimmtes Board beschränkt und an einzelne Pipeline-Stufen angehängt werden.

Jobs beobachten

Job-Typen

Job-Status

Jobs durchlaufen diese Status:

Cache-Token-Metriken

Jede Runner-Job-Ansicht zeigt Token-Nutzungsdetails einschließlich Cache-Performance an. Du kannst sehen:

• Cache Read -- Anzahl der Tokens, die aus dem Prompt-Cache bedient wurden, statt neu verarbeitet zu werden
• Cache Write -- Anzahl der Tokens, die während dieses Jobs in den Cache geschrieben wurden
• Cache Hit Rate -- Prozentsatz der Input-Tokens, die aus dem Cache bedient wurden, berechnet als Cache-Read-Tokens geteilt durch die gesamten Input-Tokens

Diese Metriken erscheinen im Ticket-Runs-Panel, in der Runner-Job-Liste, in der Übersicht aktiver Runner und in der Streaming-Job-Ansicht. Eine hohe Cache-Hit-Rate bedeutet, dass dein Runner Prompt-Kontext effizient wiederverwendet, was sowohl Latenz als auch Kosten reduziert.

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) während sie passieren
• Die Möglichkeit, 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.

Wenn der Orchestrator während der Planung einen Blocker erkennt (z.B. fehlende Informationen oder offene Fragen), zeigt die Streaming-Ansicht ein orangefarbenes "Antworten erforderlich"-Panel statt des normalen Plan-Approval-Panels. Der Genehmigen-Button wird ausgeblendet, bis der Blocker gelöst ist — nutze das Eingabefeld, um die Fragen des Agenten direkt zu beantworten.

Cache-Token-Metriken

Alle Job-Ansichten zeigen Cache-Token-Metriken an: Cache-Read-Tokens, Cache-Write-Tokens und die Cache-Hit-Rate als Prozentsatz. So siehst du, wie effizient der Runner den Context-Cache nutzt und kannst Kosten abschätzen. Cache-Metriken erscheinen im Ticket-Runs-Panel, der Runner-Job-Liste, dem Active-Runners-Widget und der Streaming-Job-Ansicht.

Was passiert, wenn ein Job fehlschlägt?

Wenn ein Runner-Job fehlschlägt, wird das Ticket automatisch in den konfigurierten Fehlerstatus des Teams verschoben und erhält ein KI fehlgeschlagen-Badge. So erkennst du sofort, welche Tickets Aufmerksamkeit brauchen. Wenn du das Ticket zurück in den Arbeitsstatus des Teams ziehst, wird das Badge entfernt und ein neuer Job automatisch erstellt.

Pro-Projekt-Runner-Setup (Build & Validate)

Jedes Projekt kann seine eigene Runner-Konfiguration haben. In den Projekt-Einstellungen kannst du im Bereich Build & Validate konfigurieren, welches Runner-Team Tickets für dieses Projekt bearbeitet und projekt-spezifisches Trigger-Verhalten festlegen. Das Setup zeigt das Arbeitsverzeichnis (/workspace/{repoName}) für jedes verbundene Repository an.

Base-Branch pro Repository

Jedes mit einem Projekt verknüpfte Repository speichert seinen eigenen Base-Branch. Wenn du ein Repository hinzufügst, übernimmt Spedy automatisch den Default-Branch des Providers (GitHub, GitLab, Bitbucket). Du kannst ihn jederzeit im Bereich Build & Validate der Projekt-Einstellungen überschreiben.

Der Base-Branch steuert:

• Den Branch, von dem der Runner neue Feature-Branches abzweigt
• Den Target-Branch für die Pull Requests, die er öffnet

Das heißt: Multi-Repo-Projekte können pro Repository einen anderen Base-Branch nutzen -- zum Beispiel main auf einem Repo und develop auf einem anderen. Die Repository-Liste zeigt für jeden Eintrag ein Badge mit dem aktuellen Base-Branch, sodass du auf einen Blick siehst, von wo aus der Runner branched und wohin er pusht.

Automatischer Retrigger bei PR-Review

Wenn ein Reviewer Änderungen an einem Pull Request anfordert, kann Spedy automatisch den Runner erneut auslösen, um das Feedback zu bearbeiten -- ohne manuelles Eingreifen.

So funktioniert es

1. Ein Runner schließt einen Job ab und öffnet einen Pull Request
2. Ein Reviewer hinterlässt eine "Changes Requested"-Review auf dem PR (GitHub oder Bitbucket)
3. Spedy empfängt den Webhook und erstellt einen neuen Runner-Job
4. Der Runner nimmt den Job an, liest die Review-Kommentare und pusht einen überarbeiteten Commit

Der neue Job enthält den vollständigen Review-Kontext: den Zusammenfassungskommentar des Reviewers und alle Inline-Kommentare mit Dateipfad, Zeilennummer und Kommentartext.

Voraussetzungen

• Git-Integration muss für das Repository aktiv sein (Einstellungen → Integrationen)
• Runner-Retrigger bei Review muss in Einstellungen → Runner → Einstellungen aktiviert sein
• Der Pull Request muss mit einem Ticket in Spedy verknüpft sein (passiert automatisch, wenn der Runner den PR erstellt)

Sicherheitsprüfungen

Spedy führt mehrere Prüfungen durch, bevor ein neuer Job ausgelöst wird, um unnötige oder doppelte Arbeit zu vermeiden:

Was der Runner erhält

Der Runner-Job-Prompt beinhaltet:

• Die ursprüngliche Ticket-Beschreibung
• Eine Zusammenfassung des Reviewer-Feedbacks
• Alle Inline-Review-Kommentare mit Dateipfad, Zeilennummer und Kommentartext
• Die PR-URL und den Branch-Namen

PR-Review-Learning

Wenn ein Runner PR-Review-Feedback verarbeitet, wird jeder Review-Kommentar als Wissenseintrag gespeichert -- mit Dateipfad, Diff-Kontext und Reviewer-Kommentar. Diese Einträge sind organisationsweit verfügbar. Wenn ein Reviewer eine Konvention auf Projekt A korrigiert, profitieren Agenten auf Projekt B beim nächsten Mal. Evergreen-Einträge mit Konfidenz >= 0.7 werden automatisch über alle Projekte geteilt.

Smarte Follow-ups

Wenn ein Follow-up-Job einen PR betrifft, der bereits gemergt oder geschlossen wurde, erkennt Spedy das automatisch. Statt den alten Branch zu aktualisieren, erstellt der Runner einen frischen Branch von main und öffnet einen neuen PR. Follow-up-Jobs werden in der UI unter dem gleichen Root-Run gruppiert.

Runner verwalten

In Einstellungen → Runner hast du fünf Tabs:

Tab Runner

• Alle verbundenen Runner mit ihrem Status sehen (Online / Offline)
• Fähigkeiten und Labels für jeden Runner anzeigen
• Sehen, wie viele Jobs jeder Runner gerade bearbeitet
• Runner-Tokens erstellen und verwalten
• Runner löschen, 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 Runner-Teams

• Runner-Teams erstellen und verwalten
• Pro-Team-Status-Zuordnungen konfigurieren (Arbeit, Abschluss, Fehler)
• @Mention-Handles für Board-Interaktions-Trigger setzen
• Pipeline-Stufen für jedes Team konfigurieren
• Pipeline-Presets wählen (Code Runner, Board Agent)

Tab Analytics

• Agenten-Performance-Metriken ansehen: Gesamtjobs, Erfolgsrate, Kosten, Tokens, durchschnittliche Dauer
• Stage-Performance-Aufschlüsselung: Dauer, Tokens und Quality-Gate-Pass-Raten pro Stufe
• Modell-Nutzungsanalyse: Token-Verbrauch nach Modell
• Tägliche Trendcharts mit konfigurierbarem Zeitraum (7d / 30d / 90d)

Tab Einstellungen

• Automatische Job-Erstellung aktivieren oder deaktivieren
• Runner-Retrigger bei Review aktivieren oder deaktivieren
• Globales Runner-Verhalten konfigurieren

Tab Secrets

• Anthropic-API-Key und beliebige Custom Env-Vars verwalten
• Maskierten Preview + letzten Rotations-Zeitstempel pro Secret sehen
• Werte hinzufügen, rotieren oder löschen — Änderungen propagieren innerhalb von 15 Minuten an alle Runner
• Erfordert die Berechtigung runners:manage-secrets (Administratoren standardmäßig)

Kostentracking & Budgets

Jeder Runner-Job trackt Kosten und Token-Verbrauch in Echtzeit, aufgeschlüsselt nach Pipeline-Stage.

Was du pro Job siehst

• Gesamtkosten in USD
• Token-Verbrauch aufgeteilt nach Input-Tokens, Output-Tokens und Cache-Tokens
• Kosten pro Pipeline-Stage (z.B. Planer, Implementierung, Review)
• Turns -- die Anzahl der Interaktionsrunden, die der Agent benötigt hat

Im Streaming-Job-View erscheinen Kosten-Updates live, während der Agent arbeitet. Der Job-Header zeigt einen Kosten/Limit-Indikator an, wenn ein Budget konfiguriert ist.

Team-Budgets

Jedes Runner-Team kann ein Standard-Budget haben. Konfiguriere es unter Einstellungen → Runner → Runner-Teams in den Team-Einstellungen:

Wenn ein Job erstellt wird, übernimmt er das Budget des Teams als Standard. Einzelne Jobs können das Team-Budget überschreiben.

Der Job-View zeigt den Budgetstatus als Fortschrittsbalken:

• Grün -- innerhalb des Budgets
• Gelb -- Warn-Schwellenwert erreicht
• Rot -- Budget überschritten

Organisations-Kostensummary

Admins können eine aggregierte Kostenübersicht über alle Runner-Jobs der Organisation unter Einstellungen → Runner einsehen. So lässt sich nachvollziehen, wo die Kosten entstehen und wo Modelländerungen oder Budget-Anpassungen sinnvoll sind.

Runner-Intelligenz

Der Runner enthält mehrere eingebaute Mechanismen, die die Agent-Effektivität verbessern, ohne dass eine Konfiguration erforderlich ist.

Knowledge Pre-Selection

Bevor ein Agent mit der Arbeit an einem Ticket beginnt, lädt der Runner automatisch relevante Wissenseinträge aus der Knowledge Base. Die Auswahl basiert auf dem Ticket-Kontext und einer Stichwortsuche. Das spart dem Agenten Turns, die er sonst für knowledge_recall-Tool-Aufrufe gebraucht hätte, und gibt ihm einen besseren Startkontext.

Diminishing Returns Detection

Der Runner trackt das Output-Token-Volumen pro Turn. Wenn ein Agent drei oder mehr Turns hintereinander weniger als 500 Output-Tokens produziert, wird das als mögliches Zeichen dafür gewertet, dass der Agent feststeckt oder nur minimalen Fortschritt macht. Diese Erkennung wird als Progress-Event gemeldet und kann für das Monitoring der Agent-Gesundheit genutzt werden.

Progress Summarizer

Alle 30 Sekunden während der Job-Ausführung generiert der Runner eine menschenlesbare Statuszusammenfassung aus Agent-Events (Tool-Calls, Textausgabe, Fehler). Diese Zusammenfassungen erscheinen in der Streaming-Job-Ansicht neben der rohen Agent-Ausgabe und erleichtern das Verständnis, was der Agent gerade tut, ohne jeden Tool-Call lesen zu müssen.

Ticket-Context-Cache

Der Runner cached Ticket-Kontextdaten für 5 Minuten. Wenn mehrere Pipeline-Stages dieselben Ticket-Informationen anfordern, löst nur die erste Stage einen API-Call aus -- nachfolgende Stages verwenden die gecachte Antwort. Der Cache wird bei Mutationen automatisch invalidiert (z.B. beim Hinzufügen eines Kommentars oder Aktualisieren der Beschreibung).

Runner-Fähigkeiten und Labels

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

• Capabilities: Die KI-Backends, die er unterstützt (z.B. claude_code). Ein Runner erhält nur Jobs, die zu seinen Fähigkeiten passen.
• Labels: Tags wie backend, frontend, python, typescript. Jobs können bestimmte Labels erfordern, sodass nur passende Runner sie aufnehmen.

Das ermöglicht spezialisierte Runner -- zum Beispiel einen für Backend-Arbeit und einen anderen für Frontend-Arbeit.

Was passiert, wenn ein Runner offline geht?

Spedy überwacht Runner über Heartbeats. Wenn ein Runner länger 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 Statusänderung in Echtzeit in der Oberfläche

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 Präfix (z.B. rnt_a3f8), um ihn zu identifizieren
• Tokens können ein Ablaufdatum haben
• Widerrufene Tokens werden sofort abgelehnt
• Du kannst einen Token auf einen bestimmten Runner einschränken für zusätzliche Sicherheit

Fehlerbehebung

Docker-Pull schlägt auf Apple-Silicon-Macs fehl (ARM64)

Wenn du einen Fehler wie diesen siehst:

no matching manifest for linux/arm64/v8 in the manifest list entries

Das Supervisor-Image ist derzeit nur für linux/amd64 gebaut. Auf Apple-Silicon-Macs füge das platform-Feld zu deiner docker-compose.yml hinzu:

services:
  supervisor:
    platform: linux/amd64
    image: ghcr.io/coding9gmbh/spedy-supervisor:latest
    # ...

Docker Desktop verwendet Rosetta, um die x86-Architektur automatisch zu emulieren.

Tipps

• Fang einfach an: Beginne mit einem Runner und den Standardeinstellungen. Skalieren kannst du später.
• Nutze Labels: Wenn du mehrere Projekte hast, verwende Labels, um Jobs an den richtigen Runner weiterzuleiten.
• Nutze Runner-Teams: Erstelle separate Teams für verschiedene Workflows (z.B. Code-Änderungen vs. Recherche-Aufgaben).
• Achte auf den Heartbeat: Wenn ein Runner als "Offline" angezeigt wird, prüfe, ob er läuft und die Spedy-API erreichen kann.
• Prüfe den Jobs-Tab: Wenn Jobs lange im Status "Ready" bleiben, stelle sicher, dass ein Runner mit passenden Fähigkeiten online ist.
• Pool-Größe: Erhöhe die Runner-Pool-Größe, wenn du mehrere Tickets parallel bearbeiten möchtest.