Den Self-hosted Runner betreiben

Standardmäßig führt kanman jede Story auf einer isolierten Maschine in Frankfurt aus. Darf dein Code dein Netz nicht verlassen, führ die Codearbeit mit dem Self-hosted Runner auf deiner eigenen Infrastruktur aus.

So funktioniert es

Der Runner ist derselbe Executor-Host, den kanman in seiner Cloud nutzt, verpackt als Docker-Image ghcr.io/kanman-ai/executor-host:

• Er holt sich Arbeit. Er baut eine ausgehende HTTPS-Verbindung zu kanman auf, meldet sich an, fragt nach dem nächsten wartenden Run deines Workspaces und meldet die Ergebnisse zurück. Keine eingehenden Ports, kein VPN, keine Firewall-Ausnahmen für kanman.
• Er authentifiziert sich mit einem Workspace-API-Token (km_...). Er erhält nie Datenbank-Zugangsdaten. Jeder Run, den er übernimmt, bekommt ein eigenes Run-Token, das mit dem Ende des Runs ungültig wird.
• Für jeden Run klont er das Repository, legt den Run-Branch an, startet das Coding-Werkzeug mit dem Auftrag des Runs und dem kanman-MCP und meldet Fortschritt, die Diff-Zusammenfassung, die Commits und ein Protokoll der Arbeit des Coding-Werkzeugs.
• Der Checkout des Repositorys bleibt auf deiner Maschine.

Was der Modellanbieter erhält, beschreibt Was Modellanbieter sehen. Das Coding-Werkzeug ruft den Anbieter vom Runner aus auf, mit dem Schlüssel, den du dem Runner mitgibst, oder bei Teams mit eigenem Schlüssel mit diesem Schlüssel.

Wie der Runner auf Arbeit wartet

Ein Run ist eine Kette von Schritten: die Programmierarbeit, danach das unabhängige Review und in manchen Workspaces Entwürfe und Aktionen im Repository drumherum. Der Runner übernimmt jeden Schritt innerhalb von etwa einer Sekunde:

• Long Poll (Standard). Der Runner fragt nach Arbeit, und kanman hält die Anfrage bis zu 25 Sekunden offen. Sobald ein Schritt in der Warteschlange steht, antwortet kanman damit. Kommt nichts, fragt der Runner sofort erneut.
• Nächster Schritt mit dem Ergebnis. Meldet der Runner einen fertigen Schritt und wartet der nächste bereits, übergibt kanman ihn in derselben Antwort. Der nächste Schritt startet ohne weitere Anfrage.
• Ausweichbetrieb. Trennt ein Proxy oder eine Firewall in deinem Netz Anfragen, die so lange offen bleiben, bemerkt der Runner das nach drei getrennten Anfragen in Folge, schreibt eine Zeile in sein Log („Long poll unavailable, polling classic until it is tried again“) und wechselt zu kurzen Anfragen alle paar Sekunden (höchstens alle 10 Sekunden). Nach 10 Minuten versucht er den Long Poll erneut.

Der Reiter Kosten & Details des Runs zeigt, wo er lief und wie schnell dein Runner seine Schritte übernommen hat, zum Beispiel „4 Schritte, übernommen nach 0,4 s (Median)“. Der Fortschritt des Runs behält pro Versuch eine Zeile dazu, wann der Run selbst übernommen wurde.

Hinweise zu Proxys. Erlaube, dass Anfragen an kanman mindestens 30 Sekunden offen bleiben (Idle- oder Read-Timeout deines Proxys). Ist das nicht möglich, setz RUNNER_LONG_POLL_MS unter die Grenze deines Proxys, zum Beispiel RUNNER_LONG_POLL_MS=10000, oder schalte den Long Poll mit RUNNER_LONG_POLL=off ab. Ohne Long Poll starten Schritte bis zu 10 bis 30 Sekunden später.

Secrets des Runners

Die Umgebung des Runners enthält Zugangsdaten: sein kanman-Token, deine Code-Host-Tokens und deinen Modellzugang. Befehle, die aus einem Repository stammen, erhalten sie nie: die Builds und Tests, die das Coding-Werkzeug in seinem Checkout ausführt, und die Anwendung, die sie aus einem Run-Branch bauen und starten.

• Was Befehle aus dem Repository sehen. Eine minimale Umgebung: PATH, HOME, Benutzer, Shell, Sprach- und Gebietsschema-Einstellungen, Zeitzone, temporärer Ordner, Proxy-Einstellungen (HTTPS_PROXY, HTTP_PROXY, NO_PROXY, ALL_PROXY), Ablageorte von Zertifikaten (NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, SSL_CERT_DIR, GIT_SSL_CAINFO, REQUESTS_CA_BUNDLE, CURL_CA_BUNDLE), LD_LIBRARY_PATH, PLAYWRIGHT_BROWSERS_PATH, NODE_OPTIONS und die Docker-Client-Einstellungen, die Compose braucht (DOCKER_HOST, DOCKER_CONTEXT, DOCKER_CONFIG, DOCKER_CERT_PATH, DOCKER_TLS_VERIFY, DOCKER_BUILDKIT, DOCKER_DEFAULT_PLATFORM, XDG_RUNTIME_DIR).
• Weitere Variablen des Runners. Braucht dein Build weitere Einstellungen des Runner-Hosts, trag deren Namen in RUNNER_COMMAND_ENV ein, zum Beispiel RUNNER_COMMAND_ENV=JAVA_HOME,MAVEN_OPTS. kanmans eigene Variablen und die Code-Host-Tokens des Runners werden nie weitergegeben. Trag dort keine Zugangsdaten ein: Alles, was du auflistest, ist für Code aus dem Repository sichtbar. Ein Team kann in seinen Einstellungen Namen seiner eigenen weiteren Variablen ergänzen (Mehrere Teams auf einem Runner).
• Werte, die deine Tests brauchen. Testkonten, Tokens von Testsystemen und ähnliche Werte gehören in die CI-Variablen deines Repositorys, wo deine Pipelines sie nutzen.
• Git-Zugriff. Der Runner nutzt sein Code-Host-Token nur für sein eigenes Klonen, Abrufen und Pushen. Das Token wird nicht in den Checkout geschrieben, deshalb können weder das Coding-Werkzeug noch Code aus dem Repository es dort lesen.
• Das Coding-Werkzeug. Claude Code oder Codex sieht die Code-Host-Tokens des Runners nie (GITHUB_TOKEN, GH_TOKEN, GITLAB_TOKEN, RUNNER_GIT_TOKEN und die üblichen CI- und CLI-Namen dafür), auch dann nicht, wenn es den Modellzugang des Runners nutzt. Das Coding-Werkzeug committet in seinem Checkout; den Run-Branch pusht der Runner, wenn das Coding-Werkzeug fertig ist.
• Commits der Arbeit des Coding-Werkzeugs. Wenn der Runner committet, was das Coding-Werkzeug hinterlassen hat, laufen keine Git-Hooks des Checkouts.

Voraussetzungen

• Ein Team mit dem Tarif Starter oder höher oder in seiner 14-tägigen Testphase des Team-Tarifs. Siehe Tarife und Abrechnung.
• Ein Linux-Host oder eine VM mit Docker. Der Runner braucht CPU und Speicher wie ein CI-Job für dein Repository.
• Für Teams mit einer Team-Umgebung: Docker, sonst nichts. Der Runner startet das Coding-Werkzeug und jede Prüfung in einem Container des Team-Images, auf dem Runner wird also keine Toolchain installiert. Läuft der Runner selbst in einem Container, binde seinen Workspace-Ordner innen und außen unter demselben Pfad ein (zum Beispiel -v /srv/kanman:/srv/kanman -e WORKSPACE_PATH=/srv/kanman), weil die Container des Teams den Checkout über seinen Pfad einbinden. Ein als Snap-Paket installiertes Docker sieht /tmp nicht: Leg Workspace und TMPDIR unter den Home-Ordner des Runners.
• Ausgehendes HTTPS zu kanman, zu deinem Git-Host und zu deinem Modellanbieter. Ein Runner im Firmennetz erreicht auch ein GitLab, das die kanman Cloud nicht sieht, über einen Proxy und mit internen Zertifikaten; siehe GitLab hinter VPN oder Firewall.
• Ein Schlüssel beim Modellanbieter für die Executors, die der Runner anbietet: ANTHROPIC_API_KEY für Claude Code, OPENAI_API_KEY für Codex. Für Teams, die in kanman einen eigenen Schlüssel nutzen, nicht nötig; ihr Schlüssel kommt mit dem Run. Teams mit Zugang deines Runners (Team > Modelle > Modellzugang) nutzen, was du auf dem Runner einrichtest, zum Beispiel dein Konto bei Amazon Bedrock, Google Vertex AI oder Microsoft Foundry, für Coding-Runs und mit Alles auf unseren auch für jeden anderen Modellschritt; siehe Modellzugang auf Self-hosted Runnern.

Schritt 1: Ein Token anlegen

Am schnellsten geht es so: Öffne Workspace-Einstellungen > Runs und Runner (oder frag kanman „Zeig mir die Runner“) und klicke auf Runner hinzufügen. Ein Fenster führt dich durch drei Schritte: Token erstellen, Runner starten und Verbinden. Gib dem Runner im ersten Schritt unter Name des Runners einen Namen (vorgeschlagen sind „Runner“ und der Tag) und klicke dann auf Token für diesen Runner erstellen. kanman legt ein Token für diesen Workspace an, das ein Jahr gilt und den Namen des Runners trägt, und der Befehl startet den Runner unter demselben Namen (RUNNER_NAME), damit du mehrere Runner und ihre Tokens auseinanderhältst. kanman setzt das Token direkt in den Befehl im nächsten Schritt ein. Kopiere den Befehl sofort: Das Token wird nur einmal angezeigt. Es steht unter Deine Einstellungen > API-Tokens, eingeklappt unter deinen persönlichen Tokens bei Runner- und Claude-Code-Tokens, wo du es widerrufen kannst.

Wenn du das Token selbst benennen oder eine kürzere Laufzeit wählen möchtest:

1. Öffne Deine Einstellungen > API-Tokens (Avatar-Menü, oder Vorhandenes Token verwenden im Fenster Runner hinzufügen) und klicke auf Token erstellen.
2. Benenne es nach dem Runner, zum Beispiel runner-fra-1, und wähle unter Workspace den Workspace, für den der Runner arbeitet.
3. Wähle eine Laufzeit (30 Tage, 90 Tage oder 1 Jahr), die zu deiner Rotationsrichtlinie passt. Der Runner braucht keine bestimmte Berechtigung; jedes aktive Token des Workspaces funktioniert.
4. Kopiere das Token. Es wird nur einmal angezeigt.

Schritt 2: Den Runner starten

Der zweite Schritt im Fenster Runner hinzufügen zeigt den Befehl mit deinem Token zum Kopieren. Der dritte Schritt zeigt Warte auf die Verbindung … und prüft alle paar Sekunden; sobald der gestartete Runner online ist, zeigt das Fenster seinen Namen, und der Runner erscheint in der Liste. Mit Namen und beiden Executors sieht der Befehl so aus:

docker run -d --name kanman-runner \
  --restart unless-stopped \
  -e KANMAN_API_KEY=km_ihr_runner_token \
  -e ANTHROPIC_API_KEY=ihr_anthropic_schluessel \
  -e RUNNER_NAME=runner-fra-1 \
  -e RUNNER_EXECUTORS=claude-code,codex \
  -e OPENAI_API_KEY=ihr_openai_schluessel \
  ghcr.io/kanman-ai/executor-host

Pinne das Image in Produktion auf eine Versionsnummer und aktualisiere bewusst.

Mit Team-Umgebungen oder Images aus deiner eigenen Registry bindest du zusätzlich den Docker-Socket und den Workspace-Ordner ein:

docker run -d --name kanman-runner \
  --restart unless-stopped \
  -e KANMAN_API_KEY=km_ihr_runner_token \
  -e RUNNER_NAME=runner-fra-1 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --group-add "$(stat -c %g /var/run/docker.sock)" \
  -v /srv/kanman:/srv/kanman -e WORKSPACE_PATH=/srv/kanman \
  ghcr.io/kanman-ai/executor-host

Schritt 3: Den Status prüfen

Öffne Workspace-Einstellungen > Runs und Runner. Der Runner erscheint mit Name, Executors, Version, dem Zeitpunkt, zu dem er zuletzt gesehen wurde, und seinem Status. Die Liste aktualisiert sich alle 30 Sekunden:

Online-Runner stehen oben, dann die, die laufende Arbeit beenden, dann die Offline-Runner nach dem Zeitpunkt, zu dem sie zuletzt gesehen wurden. Nur die drei jüngsten Offline-Runner werden gezeigt; die älteren öffnest du mit Ältere Runner (offline) anzeigen. Muss die Arbeit auf deinen Runnern laufen und ist keiner online, sagt die Seite das: Die Arbeit wartet, bis sich ein Runner verbindet. Einen Runner, der dauerhaft offline ist, entfernst du über das Menü ⋯ in seiner Zeile mit Entfernen. Er verschwindet aus der Liste, und die Jobs, die er ausgeführt hat, behalten ihren Verlauf; startet er wieder mit seinem Token, meldet er sich neu an.

Das Schaubild Wo was läuft oben auf der Seite zeigt die kanman Cloud und dein Netzwerk nebeneinander. Die kanman Cloud behält immer deine Teams und Stories, Entscheidungen, das Audit-Log sowie Run-Status und Ergebnisse. Dein Netzwerk zeigt deine Runner mit ihrem Zustand. Die Arten von Arbeit (Runs, Prüfungen, Modellaufrufe, Repository-Aktionen und Chat-Antworten) stehen dort, wo sie laufen, und wandern hinüber, wenn du änderst, wo Runs laufen. Was wo bleibt darunter erklärt die Aufteilung in Worten.

Schritt 4: Arbeit an deine Runner schicken

Die Wahl gilt für den ganzen Workspace. Öffne Workspace-Einstellungen > Runs und Runner und wähle unter Wo Runs laufen eine von drei Möglichkeiten:

Wenn du Arbeit auf deine Runner verlagerst, fragt kanman vorher nach und nennt, was wandert, denn Arbeit wartet, solange kein Runner online ist. Ab dann gehen wartende Runs aller Teams an deine Runner und werden der Reihe nach übernommen. Die Parallelität richtet sich weiter nach der Richtlinie jedes Teams und seinem Tarif. Zusätzlich begrenzt Runs gleichzeitig insgesamt im Bereich Erweitert den ganzen Workspace; der Standard ist Keine Grenze, weil der Tarif jedes Teams seine Runs schon begrenzt.

Mehrere Teams auf einem Runner

Ein Runner kann alle Teams deines Workspaces bedienen, und jedes Team bringt mit, was es braucht: einen eigenen Modellzugang, ein eigenes Code-Host-Token, weitere Variablen und die Zugangsdaten der Registry, aus der das Image seiner Team-Umgebung kommt. Teamleitungen, Owner und Admins setzen sie pro Team im Reiter Team:

So funktioniert es:

• Der Wert des Teams gilt, der Runner ergänzt den Rest. Ein für das Team gesetzter Wert ersetzt für dessen Runs und Schritte die gleichnamige Variable des Runners; alles, was das Team nicht setzt, kommt aus der Umgebung des Runners. Ein Team ohne eigene Einstellungen arbeitet genau wie bisher.
• Der Modellzugang wird als Ganzes ersetzt. Setzt ein Team eine Modellvariable, nutzt es keine Modellvariable des Runners mehr (Anbieterschlüssel, AWS_*, das KANMAN_ASSISTANT_*-Modell), damit sich nie zwei Konten mischen.
• Die Werte bleiben verschlüsselt in kanman und gehen nur mit den Runs und Schritten dieses Teams an den Runner. Der Runner hält sie für diese Arbeit im Speicher und schreibt sie nie auf die Platte. Niemand sieht einen Wert wieder: Die Einstellungen zeigen den Namen, wer ihn gesetzt hat und wann.
• Namen, die den Runner selbst steuern, kann ein Team nicht setzen: KANMAN_* (außer KANMAN_ASSISTANT_*), RUNNER_* (außer RUNNER_COMMAND_ENV), PATH, HOME, Proxy- und Zertifikatseinstellungen, GIT_*, SSH_*, DOCKER_*, LD_*, NODE_OPTIONS und ähnliche.
• Jede Änderung steht im Audit-Log mit Namen, Team und Person, nie mit dem Wert.

Was jede Art von Wert erreicht:

Alles auf deinen Runnern ausführen

Mit Unsere Runner laufen einige Schritte rund um einen Run weiter in der kanman Cloud, etwa das Entwerfen von Stories und das unabhängige Review. Um den gesamten Modellverkehr und jede Aktion in deinen Repositories in deinem Netz zu halten, wähle unter Wo Runs laufen in Workspace-Einstellungen > Runs und Runner Alles auf unseren. Siehe Alles auf deinen Runnern ausführen.

kanman im eigenen Monitoring sehen

Jeder Run hat einen Trace, der verbindet, was in kanman Cloud, auf deinem Runner und im Coding-Werkzeug passiert ist. Betreibt dein Unternehmen einen OpenTelemetry-Collector (zum Beispiel mit Grafana, Elastic oder Datadog), kann dein Runner den Trace jedes Runs dorthin senden. So sieht dein Betriebsteam kanmans Arbeit neben deinen eigenen Diensten, ohne ein weiteres Dashboard.

Setz diese Variablen am Runner und starte ihn neu:

Nach jedem Run sendet der Runner einen Span für den Run, einen für die Modellnutzung (Tokens, Kosten und die Region, in der das Modell verarbeitet hat) und einen pro Prüfung und Befehl. Befehle werden nur mit ihrem Programmnamen genannt, nie mit ihren Argumenten, und es werden keine Prompts, Antworten oder Dateiinhalte gesendet. Das Coding-Werkzeug sieht diese Variablen nie. Ohne KANMAN_OTLP_ENDPOINT wird nichts gesendet.

Skalieren und aktualisieren

• Mehr Kapazität: Starte weitere Runner mit anderen Namen, oder erhöhe RUNNER_CONCURRENCY auf einem größeren Host.
• Aktualisieren: Stoppe den Container mit genug Zeit für seine Runs, zum Beispiel docker stop --time 1800 kanman-runner. Beim Stoppen zeigt der Runner Beendet laufende Arbeit, schließt seine Runs ab und geht offline. Starte dann die neue Version.
• Token rotieren: Leg ein neues Token an, starte den Runner damit neu und widerrufe dann das alte. Ein widerrufenes oder abgelaufenes Token nimmt den Runner offline.

Fehlerbehebung