Den Self-hosted Runner betreiben

Standardmäßig führt kanman jede Story auf einer isolierten Maschine in Frankfurt aus. Darf Ihr Code Ihr Netz nicht verlassen, führen Sie die Codearbeit mit dem Self-hosted Runner auf Ihrer 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 Ihres 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 den Coding-Agenten mit dem Auftrag des Runs und dem kanman-MCP und meldet Fortschritt, die Diff-Zusammenfassung, die Commits und ein Protokoll der Arbeit des Agenten.
• Der Checkout des Repositorys bleibt auf Ihrer Maschine.

Was der Modellanbieter erhält, beschreibt Was Modellanbieter sehen. Der Coding-Agent ruft den Anbieter vom Runner aus auf, mit dem Schlüssel, den Sie dem Runner mitgeben, 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 die Akzeptanzprüfungen und in manchen Workspaces Entwürfe und Reviews 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 Ihrem 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 Ihr 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. Erlauben Sie, dass Anfragen an kanman mindestens 30 Sekunden offen bleiben (Idle- oder Read-Timeout Ihres Proxys). Ist das nicht möglich, setzen Sie RUNNER_LONG_POLL_MS unter die Grenze Ihres Proxys, zum Beispiel RUNNER_LONG_POLL_MS=10000, oder schalten Sie den Long Poll mit RUNNER_LONG_POLL=off ab. Ohne Long Poll starten Schritte bis zu 10 bis 30 Sekunden später.

Akzeptanzprüfungen auf Ihrem Runner

In einem Workspace, der seine Runs an Self-hosted Runner schickt, laufen auch die Akzeptanzprüfungen des Outcome-Gates dort: der Lauf der Spec vor der Arbeit (er muss fehlschlagen), der Lauf in einer frischen Umgebung und der Lauf auf einem sauberen Checkout. Ihre Anwendung, ihre Testdaten sowie Screenshots und Traces entstehen auf Ihrer Infrastruktur; kanman erhält das Ergebnis und die Nachweis-Artefakte für das Nachweispaket.

• Ein Runner übernimmt Akzeptanzprüfungen, wenn er Docker mit Compose erreicht und der Docker-Daemon antwortet, denn die Prüfungen starten Ihre Anwendung anhand des Akzeptanz-Manifests. Das prüft er beim Start und danach alle fünf Minuten, sodass ein behobener Docker-Zugriff ohne Neustart wirkt. Solange Docker nicht nutzbar ist, nennt das Runner-Log den Grund.
• Jede Prüfung beginnt mit einem frischen Checkout in einem temporären Ordner, nie im Ordner, in dem der Coding-Agent gearbeitet hat, und die Umgebung wird danach abgebaut.
• Ist kein Runner online, der Akzeptanzprüfungen übernehmen kann, wiederholt kanman die Prüfung zweimal und fragt Sie dann unter Entscheidungen, wie bei jedem anderen Problem der Testumgebung. Eine Prüfung, deren Runner mittendrin stoppt, geht an einen anderen Runner.

Teams mit dem Preset Testphase ohne Akzeptanz-Manifest brauchen kein Docker auf dem Runner: CI und der Reviewer laufen nicht darauf.

Secrets des Runners

Die Umgebung des Runners enthält Zugangsdaten: sein kanman-Token, Ihre Code-Host-Tokens und Ihren Modellzugang. Befehle, die aus einem Repository stammen, erhalten sie nie. Das gilt für die Befehle des Akzeptanzmanifests (Bereitstellung, Setup, Ausführung und Abbau), den lokalen Prüfbefehl und die Anwendung, die diese Befehle 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). Dazu kommt, was die Prüfung selbst mitbringt: CI=true, der Story-Schlüssel und run.env aus dem Manifest.
• Weitere Variablen des Runners. Braucht Ihr Build weitere Einstellungen des Runner-Hosts, tragen Sie 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. Tragen Sie dort keine Zugangsdaten ein: Alles, was Sie auflisten, 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 Ihre Prüfungen brauchen. Testkonten, Tokens von Testsystemen und ähnliche Werte gehören in ein Workspace-Secret, das dem Team freigegeben ist, oder in eine CI-Variable des Repositorys. Nennen Sie sie im Manifest mit run.secrets und run.ci_var_keys; siehe Secrets und CI-Variablen. Die Setup- und Spec-Befehle erhalten sie, die Werte werden aus Logs und Ausgaben entfernt und nicht mit den Nachweisen gespeichert.
• 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 der Coding-Agent noch Code aus dem Repository es dort lesen.
• Der Coding-Agent. 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 er den Modellzugang des Runners nutzt. Der Agent committet in seinem Checkout; den Run-Branch pusht der Runner, wenn der Agent fertig ist.
• Commits der Arbeit des Coding-Agenten. Wenn der Runner committet, was der Coding-Agent 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 Ihr Repository.
• Für Akzeptanzprüfungen: Docker auf dem Host. Das Runner-Image bringt den Docker-Client und das Compose-Plugin mit; binden Sie den Docker-Socket des Hosts ein und geben Sie dem Runner die Gruppe des Sockets: -v /var/run/docker.sock:/var/run/docker.sock --group-add "$(stat -c %g /var/run/docker.sock)".
• Für Teams mit einer Team-Umgebung: Docker, sonst nichts. Der Runner startet den Coding-Agent 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, binden Sie 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: Legen Sie Workspace und TMPDIR unter den Home-Ordner des Runners.
• Ausgehendes HTTPS zu kanman, zu Ihrem Git-Host und zu Ihrem 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 Modellzugang aus der Runner-Umgebung nutzen, was Sie auf dem Runner einrichten, zum Beispiel Ihr 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: Öffnen Sie Workspace-Einstellungen > Runs und Runner (oder fragen Sie kanman „Zeig mir die Runner“) und klicken Sie auf Runner hinzufügen. Ein Fenster führt Sie durch drei Schritte: Token erstellen, Runner starten und Verbinden. Geben Sie dem Runner im ersten Schritt unter Name des Runners einen Namen (vorgeschlagen sind „Runner“ und der Tag) und klicken Sie 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 Sie mehrere Runner und ihre Tokens auseinanderhalten. kanman setzt das Token direkt in den Befehl im nächsten Schritt ein. Kopieren Sie den Befehl sofort: Das Token wird nur einmal angezeigt. Es steht unter Deine Einstellungen > API-Tokens, eingeklappt unter Ihren persönlichen Tokens bei Runner- und Claude-Code-Tokens, wo Sie es widerrufen können.

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

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

Schritt 2: Den Runner starten

Der zweite Schritt im Fenster Runner hinzufügen zeigt den Befehl mit Ihrem 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

Pinnen Sie das Image in Produktion auf eine Versionsnummer und aktualisieren Sie bewusst.

Mit Team-Umgebungen, Akzeptanzprüfungen oder Images aus Ihrer eigenen Registry binden Sie 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

Öffnen Sie 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 öffnen Sie mit Ältere Runner (offline) anzeigen. Muss die Arbeit auf Ihren Runnern laufen und ist keiner online, sagt die Seite das: Die Arbeit wartet, bis sich ein Runner verbindet. Einen Runner, der dauerhaft offline ist, entfernen Sie ü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 Ihr Netzwerk nebeneinander. Die kanman Cloud behält immer Ihre Teams und Stories, Entscheidungen, das Audit-Log sowie Run-Status und Ergebnisse. Ihr Netzwerk zeigt Ihre 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 Sie ändern, wo Runs laufen. Was wo bleibt darunter erklärt die Aufteilung in Worten.

Schritt 4: Arbeit an Ihre Runner schicken

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

Wenn Sie Arbeit auf Ihre Runner verlagern, fragt kanman vorher nach und nennt, was wandert, denn Arbeit wartet, solange kein Runner online ist. Ab dann gehen wartende Runs aller Teams an Ihre 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 Ihres Workspaces bedienen, und jedes Team bringt mit, was es braucht: einen eigenen Modellzugang (zum Beispiel den Claude-Abo-Login einer Person, die kanman als eigenes Werkzeug ausprobiert), ein eigenes Code-Host-Token, weitere Variablen und die Zugangsdaten der Registry, aus der das Image seiner Team-Umgebung kommt. Owner und Admins setzen sie pro Team in den Team-Einstellungen:

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 Ihren 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 Ihren Repositories in Ihrem Netz zu halten, wählen Sie unter Wo Runs laufen in Workspace-Einstellungen > Runs und Runner Alles auf unseren. Siehe Alles auf Ihren Runnern ausführen.

kanman im eigenen Monitoring sehen

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

Setzen Sie diese Variablen am Runner und starten Sie 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. Der Coding-Agent sieht diese Variablen nie. Ohne KANMAN_OTLP_ENDPOINT wird nichts gesendet.

Skalieren und aktualisieren

• Mehr Kapazität: Starten Sie weitere Runner mit anderen Namen, oder erhöhen Sie RUNNER_CONCURRENCY auf einem größeren Host.
• Aktualisieren: Stoppen Sie 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. Starten Sie dann die neue Version.
• Token rotieren: Legen Sie ein neues Token an, starten Sie den Runner damit neu und widerrufen Sie dann das alte. Ein widerrufenes oder abgelaufenes Token nimmt den Runner offline.

Fehlerbehebung