Selbstgehostete Umgebungen in der Produktion bereitstellen

​

Härten Sie Ihre Bereitstellung

• Ephemere, sitzungsspezifische Container: Führen Sie jeden Runner-Prozess in einem frischen Container oder einer VM aus, die zerstört wird, wenn der Prozess beendet wird, mit --capacity 1 und dem Standard --drain-grace-sec 0, sodass jeder Container genau eine Sitzung bedient. Bei einer höheren Kapazität oder mit einer positiven Drain-Grace bedient ein Container mehrere Sitzungen vom selben gesperrten Owner; siehe Runner-Lebenszyklus. Verwenden Sie kein Dateisystem zwischen Runner-Neustarts wieder, außer in der absichtlichen vorgewärmten Checkout-Einrichtung, und niemals über Owners hinweg.
  • Wenn der Runner eine Sitzung beendet, sendet er kein Signal an einen Prozess, der nach dem Beenden seines Shell-Befehls noch läuft, etwa einen Dienst, der sich als Daemon abgelöst hat. Das Zerstören des Containers oder der VM beendet diesen Prozess.
• Keine breiten Anmeldedaten im Image: Fügen Sie keine langlebigen SSH-Schlüssel, Cloud-Provider-Anmeldedaten oder persönliche Zugriffstokens ein, die mehr gewähren als eine Sitzung benötigt. Erstellen Sie Anmeldedaten, die während einer Sitzung verwendet werden, wie Push- oder API-Tokens, pro Sitzung aus Ihrem Wrapper-Skript. Der anfängliche Clone findet statt, bevor der Wrapper ausgeführt wird. Verwenden Sie dafür daher einen checkout-Lebenszyklus-Hook oder --use-anthropic-git-proxy, wenn alle Repositorys einer Sitzung auf github.com liegen. Zu beiden siehe Git konfigurieren.
• Halten Sie die GitHub-Anmeldedaten des Hosts von Sitzungen fern: Claude kann alle GitHub-Anmeldedaten verwenden, die eine Sitzung lesen kann, mit dem Zugriff, den diese Anmeldedaten gewähren. Halten Sie die eigenen, weit gefassten GitHub-Anmeldedaten des Runner-Hosts aus allem heraus, was eine Sitzung lesen kann. Solche Anmeldedaten können ein persönliches Zugriffstoken sein, das Token, das gh auth login für Ihr Konto speichert, oder ein GH_TOKEN in der Umgebung des Runners.
  • Mit Anthropic-verwaltetem Git: Mit solchen Anmeldedaten erreicht Claude GitHub direkt statt über Anthropic-verwaltetes Git.
  • Ohne Anthropic-verwaltetes Git: Clone-Anmeldedaten können im Image bleiben, wenn Sie sie so eng beschränken, wie in Git-Konfiguration in Ihrem Image ausliefern beschrieben.
• Halten Sie das Umgebungsgeheimnis von sitzungsausführenden Hosts fern: Das Umgebungsgeheimnis kann Runner registrieren und jede Sitzung abholen, die in der Umgebung in die Warteschlange eingereiht ist. In einer festen Flotte lebt es auf jedem Runner-Host, wo jeder Sitzungscode das Geheimnisdatei lesen kann. Bevorzugen Sie On-Demand-Runner, bei denen das Geheimnis auf dem Orchestrator-Host bleibt, der niemals Benutzercode ausführt, und jeder Runner einen einmaligen Arbeitsauftrag erhält, der genau einen Runner registriert. Behandeln Sie in einer festen Flotte die Umgebungsgeheimnisdatei als von jeder Sitzung lesbar und rotieren Sie das Geheimnis nach jedem vermuteten Sitzungskompromiss.
• Standard-Deny-Netzwerk-Egress: Beschränken Sie den ausgehenden Datenverkehr von Runner- und Sitzungs-Containern an Ihrer eigenen Netzwerkgrenze in jeder Umgebung; Standard-Deny-Egress behandelt, was erlaubt ist und warum.
• Least-Privilege-Host-IAM: Die Compute-Identität, die an den Runner-Host angehängt ist, wie ein Instance-Profil oder ein Node-Service-Konto, sollte nur das gewähren, was der Runner selbst benötigt. Sitzungen sollten ihre eigenen Anmeldedaten über Ihr Wrapper-Skript erhalten, anstatt die des Hosts zu erben.
• Blockieren Sie den Cloud-Metadaten-Endpunkt von Sitzungen: Um Sitzungen von der Host-Identität fernzuhalten, müssen Sie ihren Zugriff auf den Cloud-Metadaten-Endpunkt blockieren, und Subnetz-Level-Egress-Richtlinien unterbrechen keinen Link-Local-Metadaten-Datenverkehr, daher blockieren Sie ihn im Container selbst:
  • IMDSv2 mit einem Hop-Limit von eins
  • GKE Workload Identity mit Metadaten-Verbergung
  • Ein explizites Deny für 169.254.169.254 im Netzwerk-Namespace des Sitzungs-Containers
  Der Block gilt auch für Ihr Wrapper-Skript und Lebenszyklus-Hooks, da sie den Container teilen. Authentifizieren Sie jeden Token-Austausch mit dem Sitzungs-JWT gegen Ihren eigenen Token-Service über zulassungslisten-Egress, oder verwenden Sie eine dateibasierte Web-Identität wie IAM Roles for Service Accounts (IRSA) auf Amazon EKS.
• Pro-Runner-Dateisystem-Isolation: Jeder Runner-Prozess erhält sein eigenes Arbeitsverzeichnis, das kein anderer Prozess auf dem Host lesen oder schreiben kann. Machen Sie --hooks-dir, das Wrapper-Skript und das ~/.claude/-Verzeichnis des Hosts für die Sitzung schreibgeschützt, entweder in das Image eingebaut oder schreibgeschützt eingebunden.
• Dispatch hat keine Pro-Umgebungs-Zugriffskontrolle: Jedes Mitglied Ihrer Anthropic-Organisation kann eine Sitzung in jede ihrer Umgebungen starten. Wenn ein Owner Claude Tag-Kanäle zur Umgebung leitet, kann jeder, den die Claude Tag-Zugriffssetting zulässt, Kanalsitzungen starten, die dort ausgeführt werden. Standardmäßig ist das jeder im verbundenen Slack-Workspace, mit oder ohne Claude-Konto. Behandeln Sie jeden Runner-Host als erreichbar für die Codeausführung durch jeden, der ihn starten kann, und platzieren Sie auf einem Runner-Host nur Daten und Anmeldedaten, die alle diese Personen lesen dürfen. --lock-to-account begrenzt, welche Konten-Sitzungen ein bestimmter Host ausführt, aber es verengt nicht, wer in die Umgebung starten kann. Um selbstgehostete Umgebungen zur einzigen Picker-Option zu machen, kann ein Owner Anthropic-gehostete Umgebungen für die ganze Organisation auf der Cloud-Umgebungen-Seite ausblenden.
• Erzwingen Sie die Repo-Settings-Guard: Wählen Sie den Guard-Modus mit --confine-repo-settings. Der Standard warn protokolliert eine Verletzung und startet die Sitzung trotzdem, enforce lehnt die Sitzung ab, und off deaktiviert den Scan. Der Runner scannt die festgeschriebenen Einstellungen jedes Repositorys auf:
  • Eine Berechtigung, die außerhalb des eigenen Workspace dieser Sitzung aufgelöst wird: ein additionalDirectories-Eintrag, eine Edit-, Write- oder NotebookEdit-Regel in permissions.allow, oder ein sandbox.filesystem.allowWrite- oder allowRead-Eintrag
  • Ein nicht leerer env-Block
  • Eine Operator-Haltungs-Überschreibung wie sandbox.enabled: false
  Die Guard läuft unabhängig von --trust-workspace und deckt keine Repository-Hooks, .mcp.json oder Bash-Regeln ab; siehe Berechtigungen und Tool-Genehmigung für den Ort dieser Berechtigungen.

​

Netzwerkanforderungen

• statsig.anthropic.com, *.sentry.io, claude.ai und platform.claude.com: Diese Hosts erscheinen in einigen älteren Enterprise-Netzwerk-Checklisten, aber der Runner erreicht sie nicht. Feature-Flag-Abrufe gehen zu api.anthropic.com, und der Runner authentifiziert sich mit dem Umgebungsgeheimnis anstelle von interaktivem OAuth.
• mcp-proxy.anthropic.com: Selbstgehostete Sitzungen verwenden es nicht. Wenn die Bereitstellung von Konnektoren für Ihre Organisation aktiviert ist, erreichen die claude.ai-Konnektoren Ihrer Organisation die Sitzungen über api.anthropic.com. Siehe MCP-Server.

• Der Einzeilen-Installer: Ruft install.sh zur Installationszeit von claude.ai ab.
• Interaktives claude auth login: Meldet sich über claude.ai, claude.com und platform.claude.com an. Das geführte Setup, der angemeldete Modus von doctor und CI-Dispatch verwenden es. Der Browser, mit dem Sie sich anmelden, lädt außerdem die Browser-Prüfungen der claude.ai-Anmeldeseite von hcaptcha.com, *.hcaptcha.com und challenges.cloudflare.com. Wenn Ihre Organisation Single Sign-On verwendet, kann dieser Browser außerdem über sso.claude.com umgeleitet werden.

​

Standard-Deny-Egress

​

Authentifizieren Sie sich bei einem Egress-Proxy

​

Wählen Sie, woher der Proxy-Authorization-Wert kommt

• --proxy-authorization-command <command>: Wählen Sie dies für ein Token, das Sie bei Bedarf generieren. Der Runner führt das Shell-Kommando aus und verwendet seine getrimmte Standardausgabe als Header-Wert, zum Beispiel Bearer <token>.
• --proxy-authorization-file <path>: Wählen Sie dies für ein Token, das ein anderer Prozess an Ort und Stelle rotiert. Der Runner liest die Datei und verwendet ihren getrimmten Inhalt als Header-Wert.

​

Konfigurationen, die der Runner ablehnt zu starten

• Beide Flags gesetzt: Ein Flag plus die Umgebungsvariable des anderen Flags zählt als Setzen beider.
• Keine Proxy-URL: Weder HTTPS_PROXY noch HTTP_PROXY enthält eine http://- oder https://-URL. Der Runner liest beide Variablen in Groß- oder Kleinbuchstaben und konsultiert nicht ALL_PROXY.
• Eines der Flags an den Orchestrator-Subcommand übergeben: self-hosted-runner orchestrator akzeptiert die Flags oder ihre Umgebungsvariablen nicht. Übergeben Sie das Flag stattdessen an jeden Runner, den der Orchestrator startet.

​

Was der Runner ändert, während ein Proxy-Autorisierungs-Flag gesetzt ist

• Listener: Der Listener ist ein Forward-Proxy auf 127.0.0.1. Der Runner startet den Listener vor der Registrierung bei der Kontrollebene und beendet sich beim Start, wenn der Listener nicht starten kann.
• Proxy-Variablen: Der Runner schreibt whichever von HTTPS_PROXY und HTTP_PROXY um, die Sie setzen, damit es auf den Listener zeigt. Dieser umgeschriebene Wert erreicht den Runner selbst, seine Lebenszyklus-Hooks und jede Sitzung, die er ausführt.
• Token-Rotation: Ein rotiertes Token wird ohne Neustart wirksam. Für jede Verbindung, die der Listener zu Ihrem Proxy öffnet, führt der Runner Ihren Befehl aus oder liest Ihre Datei erneut und fügt das Ergebnis als Header hinzu.
• Sitzungs-Umgebung: Eine Sitzung erreicht Ihren Proxy nur durch den Listener. In der Umgebung jeder Sitzung entfernt der Runner ALL_PROXY, entfernt jede Schreibweise von HTTPS_PROXY oder HTTP_PROXY, die Sie nicht gesetzt haben, und pinnt NO_PROXY auf den Wert des Runners.
• Logs: Der Runner protokolliert niemals den Header-Wert.

​

Git konfigurieren

• Lassen Sie den Runner Git konfigurieren: Starten Sie den Runner mit --configure-git, um die gleiche Identität und Commit-Signierungskonfiguration zu schreiben, die Anthropic-gehostete Sitzungen verwenden
• Versenden Sie Git-Konfiguration in Ihrem Image: Setzen Sie Identität und Push-Anmeldedaten selbst, zum Beispiel um unter Ihrer eigenen Bot-Identität zu committen

​

Lassen Sie den Runner Git konfigurieren

• user.name = Claude und user.email = noreply@anthropic.com, passend zu Anthropic-gehosteten Sitzungen
• SSH-Format-Commit- und Tag-Signierung, geleitet durch einen Runner-verwalteten Shim, der jeden Commit über Anthropic’s Signierungsservice mit den Anmeldedaten der Sitzung signiert. Signaturen sind auf GitHub gegen Anthropic’s veröffentlichten SSH-Signierungsschlüssel überprüfbar.
• push.negotiate = true, damit Git Ihren Git-Host fragt, welche Commits er bereits hat, bevor er einen Push packt. Erfordert Claude Code v2.1.257 oder später.
• core.hooksPath, das auf ein Runner-verwaltetes Hooks-Verzeichnis zeigt. Seine commit-msg- und prepare-commit-msg-Hooks fügen jedem Commit einen Co-authored-by:-Trailer für den Ersteller der Sitzung hinzu. Der Trailer wird aus der E-Mail in CCR_SESSION_ACCOUNT_EMAIL erstellt und weggelassen, wenn diese Variable nicht gesetzt ist. Wenn Ihr Image bereits core.hooksPath setzt und der Runner kein Anthropic-verwaltetes Git verwendet, behält der Runner Ihre Einstellung bei, überspringt die Installation dieser Hooks und gibt eine [runner:git]-Warnung aus.

​

Versenden Sie Git-Konfiguration in Ihrem Image

RUN git config --system user.name "Claude" && \
    git config --system user.email "noreply@anthropic.com"

• Ein SSH-Deploy-Schlüssel, der auf ein Repository mit einer url.<base>.insteadOf-Umschreibung begrenzt ist
• Ein credential.helper, der ein minimal gefasstes Token zurückgibt
• GIT_SSH_COMMAND, das auf einen eng gefassten Schlüssel zeigt

• Der Runner setzt GIT_TERMINAL_PROMPT=0, daher fragt Git nicht nach Benutzername oder Passwort.
• Der Runner führt SSH mit BatchMode=yes aus, angehängt an Ihren GIT_SSH_COMMAND, wenn Sie einen setzen, daher fragt SSH nicht nach einer Passphrase oder Host-Bestätigung.
• Der Runner setzt GCM_INTERACTIVE=never, daher öffnet Git Credential Manager keinen Anmeldedialog.
• Der Runner löscht core.askPass, daher setzen Sie es, wenn Sie einen Askpass-Helper verwenden, stattdessen durch die GIT_ASKPASS-Umgebungsvariable.

RUN git config --system --add safe.directory '*'

​

Verwenden Sie den Anthropic-Git-Proxy

• Nur github.com: Anthropic stellt Git für eine Sitzung nur bereit, wenn sich alle ihre Repositorys auf github.com befinden, und der Git-Proxy unterstützt GitHub Enterprise Server noch nicht. Auf einem Runner mit dem Git-Proxy startet eine Sitzung nicht, wenn sie ein Repository auf einem anderen Git-Host hat.
• Anmeldedaten nur für die Repositorys der Sitzung: Anthropic stellt Git-Anmeldedaten für die Repositorys bereit, die Teil der Sitzung sind, nicht für andere Repositorys auf demselben Git-Host. Ein privates Submodul, eine Abhängigkeit, die Ihr Paketmanager mit Git abruft, oder ein Plugin-Marketplace in einem anderen Repository erhält keine Anmeldedaten von Anthropic. Bitten Sie die Personen, die Sitzungen erstellen, beim Erstellen jedes Repository hinzuzufügen, das eine Sitzung benötigt. Jeder Lauf einer geplanten Cloud-Aufgabe ist eine Sitzung mit den Repositorys der Aufgabe. Bitten Sie daher den Eigentümer jeder Aufgabe, jedes Repository hinzuzufügen, das ihre Läufe benötigen.
• Nur Branch-Pushes: Ein Push, der einen Branch löscht, schlägt fehl, ebenso ein Push auf jede andere Art von Ref, etwa ein Tag. Welche Branches ein Push aktualisieren kann, erfahren Sie unter GitHub-Proxy.
• Verbundene GitHub-Konten: Bitten Sie jede Person, die Benutzersitzungen mit einem Repository erstellt, GitHub zu verbinden. Ohne ihre eigene Verbindung starten diese Sitzungen nicht.
• --capacity 1: Der Git-Proxy erfordert eine Sitzung pro Runner-Prozess, führen Sie daher mehr Replicas für Parallelität aus. Den Anthropic-Git-Proxy einschalten listet die Anforderungen auf.
• Ersetzte globale Git-Konfiguration: Der Runner löscht und ersetzt die globale Git-Konfiguration des Benutzers, unter dem er läuft. Führen Sie ihn als dedizierten Benutzer oder in einem Container aus.
• Host-Anmeldedaten für Host-Pushes: Der Push des Runners über --push-outcome-on-release und jeder Push, den Ihr post-session-Hook ausführt, verwenden weiterhin die eigenen Git-Anmeldedaten des Runner-Hosts und dessen Netzwerkpfad zu github.com. Halten Sie diese Anmeldedaten aus der globalen Git-Konfiguration heraus; Möglichkeiten, sie bereitzustellen, finden Sie unter Versenden Sie Git-Konfiguration in Ihrem Image.
• Entscheidung pro Sitzung: Anthropic entscheidet für jede Sitzung auf dem Runner, ob es deren Git bereitstellt, und eine Sitzung, für die es das nicht tut, startet nicht. Wenn Sitzungen auf einem Runner mit dem Git-Proxy nicht starten behandelt die Ursachen.

​

Den Anthropic-Git-Proxy einschalten

• Claude Code v2.1.267 oder später: Frühere Versionen akzeptieren das Flag, melden Anthropic aber nicht die Anfrage, Git bereitzustellen, und geben die Zeile Registering as opted in nicht aus, daher stellt Anthropic für ihre Sitzungen kein Git bereit.
• --capacity 1, der Standardwert: Jeder Runner-Prozess verarbeitet jeweils eine Sitzung, daher führen Sie mehr Replicas für Parallelität aus.
• Git 2.32 oder neuer: Älteres Git ignoriert die Git-Konfiguration pro Sitzung, die der Runner für den Git-Proxy einrichtet.

claude self-hosted-runner --environment-secret-file '/etc/claude/environment-secret' --base-dir '<writable-dir>' --use-anthropic-git-proxy

​

Wie Anthropic Git für eine Sitzung bereitstellt

• Benutzersitzungen: Anthropic verwendet das für den Ersteller der Sitzung gespeicherte GitHub-OAuth-Token.
• Bot- und Agentensitzungen: Anthropic verwendet das GitHub-App-Installations-Token Ihrer Organisation.
• URL-Umschreibungen: --git-host-rewrite und --git-ssh-rewrite haben keine Auswirkung auf ein Repository, das der Git-Proxy bereitstellt.

​

Wenn Sitzungen auf einem Runner mit dem Git-Proxy nicht starten

• Weder governed git ACTIVE noch die withheld-Zeile: Ein Runner, der älter als Claude Code v2.1.267 ist, protokolliert keine der beiden Zeilen, und Anthropic stellt für seine Sitzungen kein Git bereit. Aktualisieren Sie den Runner auf v2.1.267 oder später, indem Sie Die Version festlegen folgen.
• Die withheld-Zeile: Anthropic hat kein Git für die Sitzung bereitgestellt. Ein Runner, der zuvor mit dem Git-Proxy funktioniert hat, kann auf diese Weise fehlschlagen, ohne dass Sie etwas geändert haben.
  • Ein Repository liegt nicht auf github.com: Für eine Sitzung mit auch nur einem Repository auf einem anderen Git-Host, etwa GitHub Enterprise Server, wird kein Git bereitgestellt, auch nicht für ihre github.com-Repositorys. Schalten Sie den Anthropic-Git-Proxy aus für die Runner dieser Umgebung.
  • Jedes Repository liegt auf github.com: Melden Sie den Fehler Ihrem Anthropic-Account-Team mit der Sitzungs-ID aus der withheld-Zeile. Anthropic erfasst den Grund auf seiner Seite.
• Eine Zeile mit remote: access denied by the git proxy: Auch eine Sitzung, für die Anthropic Git bereitstellt, kann abgewiesen werden, zum Beispiel wenn eine Organisationsrichtlinie den Git-Zugriff für die Sitzung verweigert oder die Sitzung nicht für das Repository autorisiert ist. Das Log des Runners zeigt dann eine Zeile mit remote: access denied by the git proxy, und der Rest dieser Zeile nennt den Grund.
• GitHub authentication required: Dies erscheint, wenn der Ersteller der Sitzung keine funktionierende GitHub-Verbindung auf claude.ai hat. Der Clone der Sitzung schlägt fehl, und der Git-Fehler lautet GitHub authentication required. Please reconnect your GitHub account. Bitten Sie diese Person, GitHub in ihren claude.ai-Einstellungen zu verbinden oder erneut zu verbinden.

​

Den Anthropic-Git-Proxy ausschalten

unset CLAUDE_RUNNER_USE_GIT_PROXY

​

GitHub-API-Zugriff ohne die GitHub CLI

gh api repos/{owner}/{repo}/pulls -f title='Fix' -f head='my-branch' -f base='main'

• Anmeldedaten: Das integrierte gh sendet seine REST-Anfragen über Anthropic-verwaltetes Git, das die GitHub-Anmeldedaten auf Anthropic’s Seite bereitstellt, daher benötigt das Image dafür kein GitHub-Token
• Welche Sitzungen es erhalten: Anthropic entscheidet pro Sitzung, ob Anthropic-verwaltetes Git das gh der Sitzung bedient. Wenn ja, zeigt die Zeile [runner:session] governed git ACTIVE, die der Runner für die Sitzung protokolliert, gh_path_shim=true. Wenn nicht, hat die Sitzung kein gh
• jq: Installieren Sie jq im Image, wenn --jq funktionieren soll
• CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: Wenn die Sitzungsumgebung diese Variable setzt, stellt Claude Code das integrierte gh nicht bereit, und die Sitzung hat kein gh

​

Vertrauen Sie einer privaten Zertifizierungsstelle mit Anthropic-verwaltetem Git

• System-Zertifikatspeicher: Installieren Sie Ihre CA im System-Zertifikatspeicher des Runner-Hosts, und Git vertraut ihr ohne eine der beiden Variablen.
• GIT_SSL_CAINFO: Setzen Sie sie auf eine PEM-Datei Ihrer CAs, zum Beispiel GIT_SSL_CAINFO=/etc/ssl/corp-ca.pem.
• GIT_SSL_NO_VERIFY: hilft nicht hinter einem Neu-Signierungs-Proxy. Der Runner’s eigener Clone durch Anthropic-verwaltetes Git überprüft Zertifikate auch wenn die Variable gesetzt ist, daher schlägt dieser Clone fehl, bis Git Ihrer CA durch einen der anderen beiden Ansätze vertraut.

• GIT_SSL_CAINFO: Was Git gegen Anthropic-verwaltetes Git überprüft, hängt davon ab, wo Git ausgeführt wird:
  • Runner’s eigener Clone und Abrufe: Laufen ohne die Variable und überprüfen Anthropic-verwaltetes Git gegen eine Pro-Sitzungs-Zertifikatsdatei, die der Runner schreibt. Der Runner erstellt diese Datei aus dem System-CA-Bundle des Runner-Hosts und den Zertifikaten in Ihrer Datei.
  • Git innerhalb der Sitzung: Erhält http.sslCAInfo-Konfiguration, die Ihre Datei anstelle der Variable benennt, plus http.<url>.sslCAInfo-Einträge, die Anthropic-verwaltetes Git gegen die Pro-Sitzungs-Datei überprüfen.
  • checkout- und post-session-Hooks: Erben die Variable unverändert.
• GIT_SSL_NO_VERIFY: Welche Zertifikatsüberprüfungen ausgeschaltet bleiben, hängt davon ab, wo Git ausgeführt wird:
  • Runner’s eigener Clone und Abrufe: Laufen ohne die Variable und überprüfen das Zertifikat, das ihnen präsentiert wird.
  • Git innerhalb der Sitzung: Erhält http.sslVerify=false-Konfiguration anstelle der Variable, daher bleiben Überprüfungen für andere Hosts ausgeschaltet. Es erhält auch http.<url>.sslVerify=true-Einträge, die Überprüfungen für Anthropic-verwaltetes Git eingeschaltet halten.
  • checkout- und post-session-Hooks: Wenn die Sitzung ein Repository auf Anthropic-verwaltetem Git hat, erhalten http.sslVerify=false-Konfiguration anstelle der Variable. Sie erhalten auch http.<url>.sslVerify=true-Einträge, die Überprüfungen für Anthropic-verwaltetes Git eingeschaltet halten.

​

github.com-Repositorys zu Claude Tag-Channel-Sitzungen hinzufügen

​

Schreiben Sie Git-URLs für private Netzwerke um

• --git-host-rewrite <from>=<to>: für Split-Horizon-DNS, wo Anthropic Ihren Git-Host über einen externen Hostnamen erreicht, aber Runner einen internen verwenden müssen
• --git-ssh-rewrite <host>: für Git-Hosts, die nur SSH akzeptieren, oder einen Runner-Host, der nur einen SSH-Schlüssel hat. Um beispielsweise github.com-Repositorys über SSH zu klonen, fügen Sie dem Runner-Befehl --git-ssh-rewrite github.com hinzu. Der Runner schreibt dann https://github.com/owner/repo in git@github.com:owner/repo um. SSH muss ohne Eingabeaufforderung eine Verbindung herstellen.

​

Erstellen Sie das Runner-Image

FROM debian:bookworm-slim
ARG CLAUDE_CODE_VERSION
RUN apt-get update && apt-get install -y --no-install-recommends git curl ca-certificates openssh-client jq python3 \
 && rm -rf /var/lib/apt/lists/*
RUN curl -fsSL "https://downloads.claude.ai/claude-code-releases/${CLAUDE_CODE_VERSION:?set with --build-arg CLAUDE_CODE_VERSION}/linux-x64/claude" \
      -o /usr/local/bin/claude && chmod +x /usr/local/bin/claude
RUN git config --system user.name "Claude" \
 && git config --system user.email "noreply@anthropic.com" \
 && git config --system --add safe.directory '*'
ENTRYPOINT ["claude"]

docker build \
  --build-arg CLAUDE_CODE_VERSION="$(curl -fsSL https://downloads.claude.ai/claude-code-releases/stable)" \
  -t <your-registry>/claude-runner:latest .

​

Dimensionieren Sie CPU und Speicher für Sitzungen

• Speicher: eine Anfrage und ein Limit von jeweils 4 GiB, was das 4-GB-Minimum in Claude Code’s Systemanforderungen erfüllt. Halten Sie die beiden gleich, damit der Scheduler die volle Speicherkapazität des Containers berücksichtigt. Wenn der Container sein Speicherlimit erreicht, tötet der Kernel Prozesse darin, was eine Sitzung mitten in einer Aufgabe beenden kann.
• CPU: eine Anfrage von 2 CPUs und ein Limit von 4 CPUs, daher kann eine Sitzung während Builds über die Anfrage hinaus platzen. Der Kernel drosselt einen Container bei seinem CPU-Limit, anstatt Prozesse darin zu töten, daher laufen Sitzungen am Limit langsamer, aber laufen weiter.

resources:
  requests:
    cpu: "2"
    memory: 4Gi
  limits:
    cpu: "4"
    memory: 4Gi

• Eine Sitzung pro Runner: Geben Sie jedem Container die Werte einer Sitzung. Verwenden Sie diese Dimensionierung bei --capacity 1, das der Härtungsabschnitt empfiehlt, und für On-Demand-Runner, wo Sie die Werte auf der Workload setzen, die Ihr spawn-runner-Hook einreicht, wie ein Kubernetes Job’s Pod-Template.
• Mehrere Sitzungen pro Runner: Bei einem --capacity über eins multiplizieren Sie die Werte einer Sitzung mit der Kapazität, weil bis zu so viele Sitzungen gleichzeitig im Container laufen können. Die Kubernetes- und Docker Compose-Rezepte führen --capacity 4 ohne CPU- oder Speicherlimits aus, daher fügen Sie Limits hinzu, die für die Kapazität dimensioniert sind, die Sie ausführen.
• Mehrere Runner-Container auf einem Host: Dimensionieren Sie den Host für die Summe der Kapazitäten der Runner, weil jeder Runner nur seine eigenen Sitzungen auf --capacity anrechnet:
  • Speicher: Multiplizieren Sie den Speicher einer Sitzung mit der Summe und addieren Sie dann, was die eigenen Prozesse des Hosts verwenden
  • CPU: Multiplizieren Sie die CPU-Anfrage einer Sitzung mit der Summe. Damit jede Sitzung gleichzeitig über ihre Anfrage hinausgehen kann, multiplizieren Sie stattdessen ihr CPU-Limit.
  Geben Sie jedem Runner einen eigenen Container. Verwenden Sie in jedem denselben --base-dir-Pfad, auf einem Datenspeicher, den kein Container eines anderen Runners einbindet, damit jeder Runner ein eigenes Arbeitsverzeichnis hat.

​

Geben Sie jeder Sitzung ein eigenes Speicherlimit

• In einem Container: Führen Sie einen Runner pro Container aus und setzen Sie das Speicherlimit des Containers, etwa limits.memory unter Kubernetes, --memory unter Docker oder mem_limit in einer Compose-Datei. Halten Sie die Summe der Limits der Container unter dem Speicher des Hosts, denn wenn dem Host selbst der Speicher ausgeht, kann der Kernel Prozesse an beliebiger Stelle auf dem Host beenden.
• Unter systemd ohne Container: Setzen Sie MemoryMax für die Unit des Runners und führen Sie einen Runner pro Host aus, denn Runner, die dasselbe --base-dir auf einem Dateisystem verwenden, teilen sich die dort geklonten Repositorys. Beispielsweise können ihre Sitzungen bei --capacity 1 ohne checkout-Hook gleichzeitig im selben Checkout eines Repositorys arbeiten. Um mehrere Runner auf einem Host auszuführen, geben Sie jedem einen Container.

​

Lassen Sie Spielraum unter Prozess- und Thread-Limits

​

Wo Sie jedes Limit setzen

​

Messen Sie den Spitzenwert einer Sitzung

​

Prüfen Sie ein pids.max-Limit

• Prüfen, ob pids.max erreicht wurde: Durchsuchen Sie das Kernel-Log des Hosts, zum Beispiel mit dmesg, nach einer Zeile, die cgroup: fork rejected by pids controller in und den Pfad einer cgroup enthält. Der Kernel protokolliert sie nur beim ersten Mal, wenn er in dieser cgroup einen Prozess oder Thread verweigert, durchsuchen Sie daher das gesamte Log.
• Das geltende Limit anzeigen: Lesen Sie pids.max im cgroup-Verzeichnis des Runners und in jedem darüberliegenden Verzeichnis. Der niedrigste Wert ist das geltende Limit, und max bedeutet, dass auf dieser Ebene kein Limit besteht.

​

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: claude-runner
  namespace: claude-runners
spec:
  replicas: 3
  selector:
    matchLabels:
      app: claude-runner
  template:
    metadata:
      labels:
        app: claude-runner
        app.kubernetes.io/part-of: claude-code-self-hosted-runner
    spec:
      terminationGracePeriodSeconds: 90
      containers:
        - name: runner
          image: <your-registry>/claude-runner:latest
          args:
            - self-hosted-runner
            - --environment-secret-file
            - /etc/claude/environment-secret
            - --capacity
            - "4"
            - --base-dir
            - /workspace
          volumeMounts:
            - name: environment-secret
              mountPath: /etc/claude
              readOnly: true
          ports:
            - name: health
              containerPort: 8080
          readinessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 5
            periodSeconds: 10
          livenessProbe:
            httpGet:
              path: /healthz
              port: 8080
            initialDelaySeconds: 30
            periodSeconds: 30
      volumes:
        - name: environment-secret
          secret:
            secretName: claude-runner-environment-secret

kubectl create namespace claude-runners

kubectl create secret generic claude-runner-environment-secret -n claude-runners --from-file=environment-secret=./environment-secret

​

Docker Compose

services:
  claude-runner:
    image: <your-registry>/claude-runner:latest
    command:
      - self-hosted-runner
      - --environment-secret-file
      - /run/secrets/environment-secret
      - --capacity
      - "4"
      - --base-dir
      - /workspace
    secrets:
      - environment-secret
    restart: always
    stop_grace_period: 90s

secrets:
  environment-secret:
    file: ./environment-secret

​

Zeitverhalten beim Herunterfahren

1. Der Runner wartet bis zu --drain-wait-sec Sekunden, standardmäßig 0, darauf, dass noch laufende Turns abgeschlossen werden.
2. Er beendet den Prozessbaum jeder Sitzung, einschließlich aller Befehle, die Claude noch ausgeführt hat, jedoch nicht einen Prozess, der nach dem Ende seines Shell-Befehls noch läuft.
3. Er führt den post-session-Lifecycle-Hook aus.

• --drain-wait-sec für Schritt 1, standardmäßig 0 Sekunden
• --session-stop-grace-sec für Schritt 2, standardmäßig 5 Sekunden
• --post-session-hook-timeout-sec für Schritt 3, standardmäßig 60 Sekunden
• Ein fester Puffer von 15 Sekunden
• Weitere 30 Sekunden, wenn --push-outcome-on-release gesetzt ist

• Mit --retire-at: Bemessen Sie den Abstand zwischen dem Retire-Zeitpunkt und dem Stopp-Zeitpunkt des Hosts so, dass er typische Turns abdeckt, zuzüglich der Wartezeit für Hintergrundaufgaben, die unter Runner-Lebenszyklus beschrieben ist, zuzüglich der protokollierten Dauer. Berechnen Sie den Retire-Zeitpunkt bei jedem Start, beispielsweise date +%s plus die vorgesehene Lebensdauer des Runners.
• Mit --defer-shutdown-max-min: Das Stopp-Timeout muss zusätzlich die von Ihnen konfigurierten Minuten abdecken sowie eine weitere Wartezeit vor Beginn des Drains, mit Standardeinstellungen 75 Sekunden. Das Leeren über das erste Signal hinaus aufschieben erläutert beides. Der Runner protokolliert diese längere Dauer ebenfalls beim Start.

​

Laufende Turns vor einem Neustart abschließen lassen

• --drain-wait-sec: etwa so lange wie die Turns und Hintergrundaufgaben, die Sie abschließen lassen möchten. Es handelt sich um einen Höchstwert: Die Wartezeit endet früher, wenn sie zuerst abgeschlossen sind.
• Ihr Stopp-Timeout: terminationGracePeriodSeconds in Kubernetes, stop_grace_period in Docker Compose. Ersetzen Sie beispielsweise bei --drain-wait-sec 120 die 90 im Rezept für Kubernetes oder Docker Compose durch 200.
• Wenn Sie andere Einstellungen für das Herunterfahren geändert haben: Die 80 Sekunden gelten für Standardeinstellungen. Starten Sie einen Runner mit Ihren Flags und verwenden Sie mindestens die Zahl in seiner Startzeile This runner needs up to, die die Wartezeit einschließt. Wenn --defer-shutdown-max-min gesetzt ist, verwenden Sie die größere Zahl in der nächsten Startzeile, nach Size the stop timeout to at least. Zeitverhalten beim Herunterfahren listet auf, was zu diesen Zahlen beiträgt.

​

Vor einem Neustart eine Statusmeldung veröffentlichen

​

Das Leeren über das erste Signal hinaus aufschieben

​

Was nach dem ersten Signal mit den vom Runner gehaltenen Sitzungen geschieht

• Während der ersten n Minuten: Der Runner bedient seine Sitzungen normal und setzt --startup-timeout-min und --kill-session-after-min weiterhin durch. Wenn Sie zusätzlich --release-idle-session-min setzen, gibt der Runner jede Sitzung frei, deren Benutzer so lange inaktiv war; ohne dieses Flag bleiben inaktive Sitzungen auf dem Runner.
• Wenn die n Minuten abgelaufen sind: Der Runner gibt jede Sitzung frei, die er noch hält, ob inaktiv oder nicht. Bei einer Sitzung mitten in einem Turn wartet der Runner, bis der Turn endet, und bis zu 60 weitere Sekunden auf die Hintergrundaufgaben des Turns, bevor er diese Sitzung freigibt.
• Wenn die Grace nach der Freigabe abgelaufen ist: Der Runner leert alle Sitzungen, die er noch hält, und die Control Plane reiht jede geleerte Sitzung sofort bei einem anderen Runner neu ein. Die Grace nach der Freigabe beginnt, wenn die n Minuten abgelaufen sind, und beträgt mit Standardwerten 75 Sekunden. Wenn Sie --drain-wait-sec auf mehr als 60 Sekunden setzen, beträgt die Grace nach der Freigabe stattdessen --drain-wait-sec plus 15 Sekunden.

​

Das Stopp-Timeout bemessen

​

Was einen laufenden post-session-Hook erreicht

• Ein SIGTERM, während der Runner bereits leert: erzwingt das sofortige Beenden des Runners und überspringt den verbleibenden Rest des Drains. Ohne --defer-shutdown-max-min ist das das zweite SIGTERM, das der Runner empfängt. Nichts sendet einem laufenden post-session-Hook ein Signal, sodass er auf einem Bare-Host, auf dem ein Init-Prozess verwaiste Prozesse übernimmt, eigenständig zu Ende läuft, jedoch unbeaufsichtigt: Sein Timeout-Budget gilt nicht mehr, und ein Schreibvorgang in die geschlossene Log-Pipe kann ihn mit SIGPIPE beenden. Ein Hook, der dort ein erzwungenes Beenden überstehen muss, sollte seine eigene Ausgabe daher in eine Datei umleiten. In den Container-Rezepten auf dieser Seite ist der Runner PID 1 des Containers und sein Beenden beendet den Container, und unter dem systemd-Standard KillMode=control-group erreicht das cgroup-weite Beenden auch den Hook, wie der Eintrag Cgroup-weite Kills beschreibt; behandeln Sie in beiden Fällen ein erzwungenes Beenden als fatal für den Hook und verlassen Sie sich stattdessen auf die Grace Period.
• Prozessgruppenweite Signale, etwa kill -- -<pid> in einem Wrapper-Skript, Shell-Jobsteuerung oder ein gruppenweiter Watchdog: erreichen den Runner und einen Unterprozess eines laufenden checkout-Hooks, der absichtlich an die Gruppe gebunden bleibt, aber keinen laufenden post-session-Hook und nicht den Sitzungs-Kindprozess.
• Cgroup-weite Kills, etwa der systemd-Standard KillMode=control-group oder das SIGKILL, das Kubernetes an den gesamten Container sendet, wenn terminationGracePeriodSeconds abläuft: erreichen alles, einschließlich des Hooks. Die Isolation der Prozessgruppe schützt davor nicht, weshalb die Grace Period den gesamten Drain abdecken muss.
• Das eigene Timeout des Hooks: Wenn ein Hook --post-session-hook-timeout-sec überschreitet, sendet der Runner SIGTERM an die gesamte Prozessgruppe des Hooks und zwei Sekunden später SIGKILL, sodass ein vom Hook abgespaltener Worker, etwa tar, rsync oder git, zusammen mit der Wrapper-Shell beendet wird, statt als verwaister Prozess weiterzuleben. Die Überwachung durch den Runner endet, sobald die stdio des Hooks geschlossen wird: Ein Worker, der seine eigene Ausgabe in eine Datei umgeleitet hat und die SIGTERM-Phase überlebt, liegt außerhalb der Reichweite des Runners.

​

Halten Sie das Basis-Verzeichnis und die Kapazität über Runner identisch

​

Wiederverwendung eines vorgewärmten Checkouts

• Bei --capacity 1: Der Runner ruft die angeforderte Referenz ab, trennt HEAD ab und setzt hart darauf zurück, was nahezu augenblicklich ist, wenn sich wenig geändert hat.
• Bei einer --capacity größer als eins: Der Runner ruft in diesen Klon ab und checkt dann für jede Sitzung einen separaten Worktree daraus aus. Ein vorgewärmter Klon spart den Download, aber nicht den Checkout.

• Klon im Image: Erstellen Sie den Klon in Ihrem Runner-Image unter diesem Pfad. Jeder neue Container startet dann mit dem warmen Klon, ohne eine Festplatte wiederzuverwenden.
• Klon auf einem persistenten Volume: Bei Runnern, die Sie mit --lock-to-account auf das Konto eines Benutzers sperren, verweisen Sie --base-dir auf ein persistentes Volume, sodass die Festplatte nur diesem Konto dient. Ein gesperrter Runner akzeptiert niemals Claude Tag Channel-Sitzungen, daher gilt diese Option nicht für Runner, die diese bedienen.

• Klontiefe: Erstellen Sie den Klon ohne --depth, mit oder ohne --single-branch. Der Runner übergibt niemals --depth, wenn er in einen Klon mit einem origin-Remote abruft, selbst wenn Sie CLAUDE_RUNNER_FETCH_DEPTH festlegen. Bei einem vollständigen Klon lädt jede Sitzung nur die Commits herunter, die dem Klon fehlen. Bei einem flachen Klon lädt eine Sitzung auf einem Branch, der vor dem ältesten Commit des Klons abgezweigt wurde, die gesamte Historie dieses Branches herunter.
• Nachverfolgte Änderungen werden zurückgesetzt, nicht nachverfolgte Dateien bleiben erhalten: Bei --capacity 1 beginnt jede Sitzung mit einem harten Zurücksetzen, das die nachverfolgten Änderungen der vorherigen Sitzung löscht, aber der Runner führt niemals git clean aus, daher bleiben nicht nachverfolgte Dateien aus früheren Sitzungen des gesperrten Besitzers im Baum.
• Per-Session-Verzeichnisse bleiben ebenfalls erhalten: Neben dem Checkout erstellt der Runner für jede Sitzung, die er ausführt, Einträge pro Sitzung unter <base-dir>/_sessions/. Das Claude-Konfigurationsverzeichnis der Sitzung enthält eine lokale Kopie des Gesprächstranskripts. Daneben befinden sich die hochgeladenen Dateien der Sitzung, falls die Sitzung welche hat. Das Sitzungsverzeichnis befindet sich auch dort: Es enthält alle Pro-Session-Worktrees und checkout Hook-Checkouts während der Sitzung ausgeführt wird, und es behält alles andere, was Claude darin geschrieben hat. Standardmäßig lässt der Runner diese an Ort und Stelle, wenn die Sitzung endet, daher sammeln sie sich auf einer Festplatte an, die den Runner-Prozess überlebt. Jede Sitzung wird als eigener Benutzer des Runners ausgeführt, daher kann jede spätere Sitzung, die diese Festplatte bedient, sie lesen. Wenn Sie ein persistentes --base-dir beibehalten, dimensionieren Sie das Volume für dieses Wachstum. Das Gleiche gilt für jedes Setup, das den Runner auf demselben Dateisystem neu startet, einschließlich des Docker Compose-Rezepts.
• Mit --remove-session-state bleiben Per-Session-Verzeichnisse nicht erhalten: Starten Sie den Runner mit --remove-session-state, um ihn dazu zu bringen, die Per-Session-Verzeichnisse jeder Sitzung zu löschen, wenn die Sitzung endet. Das Löschen ist bestmöglich: Die Verzeichnisse bleiben erhalten, wenn der Runner beendet wird, bevor seine Bereinigung ausgeführt wird. Der kanonische Klon und Dateien, die eine Sitzung an anderer Stelle auf dem Host geschrieben hat, wie das temporäre Verzeichnis, bleiben unabhängig davon erhalten.
• Mit dem Git-Proxy wird das Zurücksetzen zu einem Checkout: Mit --use-anthropic-git-proxy bereinigt der Runner das .git/-Verzeichnis des Klons vor jeder Sitzung. Er behält den Objektspeicher und den flachen Zustand und löscht den Index. Ohne den Index beginnt jede Sitzung mit einem vollständigen Working-Tree-Checkout anstelle eines nahezu augenblicklichen Zurücksetzens. Der Runner ruft weiterhin in den vorhandenen Klon ab, anstatt das Repository erneut zu klonen. Submodul-Vorwärme wird unter dem Proxy nicht unterstützt.
• Mit dem Git-Proxy verliert ein reftable-Vorwärm seine Referenzen: Wenn der Runner .git/ vor jeder Sitzung bereinigt, behält er .git/refs/ und entfernt das Verzeichnis .git/reftable/. Ein im reftable-Referenzformat von Git vorgewärmter Klon verliert auf diese Weise seine Referenzen. Wärmen Sie den Klon daher stattdessen im files-Referenzformat von Git vor.
• Lange Klone benötigen keine Umgehung: Der Runner begrenzt jede Git-Operation mit einem 120-Sekunden-Watchdog ohne Fortschritt und einer 30-Minuten-Obergrenze, nicht mit einem flachen Timeout, daher wird ein langsamer kalter Klon, der weiterhin Fortschritt meldet, abgeschlossen.

​

Bestätigen, dass der Runner Ihren Klon verwendet

​

Pinnen Sie die Version

• Bevor Sie eine Version pinnen: Überprüfen Sie die Claude-Code-Versionen, die Modelle erfordern für jedes Modell, das Ihre Sitzungen verwenden. Wenn ein Modell eine neuere Version erfordert als die, die Ihre Sitzungen ausführen, lehnt der Server Anfragen für dieses Modell mit Claude Code unterstützt dieses Modell nicht ab.
• Um eine Flotte auf einer Version zu halten: Erstellen Sie das Image mit einer gepinnten Version, oder installieren Sie auf einem bloßen Host eine spezifische Version und deaktivieren Sie Auto-Updates
• Um eine feste Flotte zu aktualisieren: Lesen Sie die Changelog-Einträge zwischen Ihrer Version und der Version, die Sie installieren, und installieren Sie dann die neuere Version oder bauen Sie das Image neu und starten Sie die Runner neu
• Um bedarfsgesteuerte Runner zu aktualisieren: Lesen Sie die Changelog-Einträge zwischen Ihrer Version und der Version, die Sie installieren, und ändern Sie dann das Image, das Ihr spawn-runner-Hook startet. Jeder neue Runner erhält die neue Version. Ein bereits laufender Runner, einschließlich eines Standby-Runners, den --min-idle gestartet hat, behält seine Version, bis er beendet wird. Starten Sie ihn nicht neu, da sein Arbeitsauftrag nur einmal verwendet werden kann.
• Wenn Sitzungen eine andere Binärdatei starten: Wenn Sie --exec-path oder einen command-Hook verwenden, um eine andere Claude-Code-Binärdatei als die des Runners zu starten, führen Sitzungen die Version dieser Binärdatei aus. Aktualisieren Sie diese Binärdatei, wenn Sie den Runner aktualisieren.
• Plugins: Plugin-Marktplätze auto-updaten auch nicht; setzen Sie FORCE_AUTOUPDATE_PLUGINS=1 in der Runner’s Umgebung, um Plugins auto-updaten zu lassen, während die Binärdatei gepinnt bleibt

​

Skalieren Sie die Flotte

• Feste Flotte: Führen Sie einen statischen Satz von Runner-Replicas aus und skalieren Sie auf den Prometheus-Metriken, die jeder Runner bedient
• On-Demand-Runner: Führen Sie den claude self-hosted-runner orchestrator-Subcommand aus, der Anthropic auf Sitzungen abfragt, die mit keinem verfügbaren Runner in die Warteschlange eingereiht sind und Ihren spawn-runner-Hook aufruft, um einen pro Sitzung zu starten. Siehe On-Demand-Runner.

​

Inaktive Sitzungen in einer festen Flotte freigeben

• Zeitreihen über diesem Wert, etwa 1800 für 30 Minuten: Inaktive Sitzungen belegen diese Slots, setzen Sie daher --release-idle-session-min
• Alle Zeitreihen darunter: Keine Sitzung war so lange inaktiv. Fügen Sie Runner hinzu oder setzen Sie --kill-session-after-min für Sitzungen, die nie inaktiv werden.
• Ein Runner ohne Zeitreihe: Keine Sitzung belegt ihn. Siehe Sitzungen bleiben in der Warteschlange unter Fehlerbehebung.
• Ein Runner, dessen Metriken nicht antworten: Sein Prozess wurde möglicherweise beendet. Siehe Eine Umgebung, die fehlerfrei aussieht unter Wenn der Runner beendet wird.

• Nicht gepushte Arbeit: Eine freigegebene Sitzung wird bei ihrer nächsten Nachricht fortgesetzt, jedoch ohne die Arbeit, die sie nicht gepusht hatte. Wie Sie ihre Commits behalten, erfahren Sie unter Fortgesetzte Sitzungen verlieren nicht gepushte Arbeit.
• Runner wird beendet: Ein Runner, der seine letzte Sitzung freigibt, leitet ein normales Beenden ein. Lassen Sie ihn von Ihrem Supervisor auf einem frischen Dateisystem neu starten, wie unter Härten Sie Ihr Deployment beschrieben.
• Sitzungen, die nie inaktiv werden: Setzen Sie zusätzlich --kill-session-after-min, da manche Sitzungen nicht als inaktiv gelten

​

Bekannte Probleme und Einschränkungen

​

Connector-Datenverkehr verlässt Ihr Netzwerk

• https://api.anthropic.com/v2/ccr-sessions/*
• https://api.anthropic.com/v1/code/sessions/*
• https://api.anthropic.com/v1/code/mcp/*

​

Einige Sitzungen zählen nicht als untätig

• Wenn die Sitzung auf ihren Benutzer wartet, gibt der Runner sie frei. Wenn ihr Zug beendet ist und sie hält nur Hintergrund-Tasks, wartet der Runner bis zu 60 Sekunden, damit diese Tasks fertig werden, und gibt sie dann frei. Die Sitzung wird fortgesetzt, wenn ihr Benutzer ihre nächste Nachricht sendet.
• Wenn ein Zug noch läuft, wartet der Runner darauf, dass der Zug fertig wird, oder dass die Sitzung das nächste Mal auf ihren Benutzer wartet, und gibt sie dann frei.
• Wenn die Sitzung noch auf dem Runner ist, wenn das Kulanzfenster endet, beendet der Runner sie, und jede laufende Zug-Arbeit geht verloren. Ein Zug, der auf eine Genehmigung wartet, die von innerhalb eines laufenden Tool-Aufrufs angefordert wird, ist eine Möglichkeit, wie eine Sitzung das Fenster überlebt.

​

Zusätzliche Einschränkungen

• Fortgesetzte Sitzungen verlieren nicht gepushte Arbeit: Ein frischer Runner klont das Repository erneut von seinem Start-Branch, daher ist Arbeit, die die Sitzung nicht gepusht hat, verloren.
  • Um committete Arbeit zu behalten: Setzen Sie --push-outcome-on-release auf jedem Runner in der Umgebung, da ein Runner ohne das Flag die Sitzung von ihrem Start-Branch aus fortsetzt. Ein Runner mit dem Flag führt vor der Freigabe einen Best-Effort-Push der Ergebnis-Branches der Sitzung durch, und die fortgesetzte Sitzung startet von diesen Commits. Der Push verwendet die eigenen Git-Anmeldedaten des Runner-Hosts, auch auf einem Runner, der von Anthropic verwaltetes Git verwendet.
  • Mit einem checkout-Hook: Repositorys, die über einen checkout-Lifecycle-Hook ausgecheckt werden, werden nicht gepusht. Sichern Sie diese stattdessen über den post-session-Hook.
  • Bevor Sie das Flag aktivieren: Beschränken Sie, wer zu claude/*-Refs auf dem Quell-Remote pushen kann. Beim Fortsetzen ruft der Runner den zuvor gepushten Branch ab, ohne zu überprüfen, wer ihn gepusht hat.
  • Nicht committete Änderungen gehen weiterhin verloren: Wie Sie Claude per Prompt anweisen, nach Abschluss seiner Antwort zu committen und zu pushen, erfahren Sie unter Sitzungen zum Pushen ihrer Arbeit auffordern
• Ein durch einen verlorenen Runner abgebrochener Befehl kann erneut ausgeführt werden: Wenn die Sitzung auf einem anderen Runner fortgesetzt wird, sieht Claude den unterbrochenen Tool-Aufruf mit einem Ergebnis, das besagt, dass sein Ausgang unbekannt ist.
• Ein während der Sitzung hinzugefügtes Repository kann beim Klonen fehlschlagen: Claude klont es mit git clone über HTTPS. Auf einem Runner ohne --use-anthropic-git-proxy schlägt das Klonen mit einem Git-Authentifizierungsfehler fehl, wenn nichts auf dem Host das Repository lesen kann. Wählen Sie nach Möglichkeit jedes Repository, das die Sitzung benötigt, bereits beim Erstellen aus.
• Einige Connectoren erscheinen nicht in selbstgehosteten Sitzungen: Ein Connector, den Sie noch nicht in claude.ai Settings verbunden haben, wird nicht in einer selbstgehosteten Sitzung aufgelistet, und die Sitzung wird Sie nicht auffordern, ihn zu verbinden. Verbinden Sie ihn zuerst in Settings, dann starten Sie eine frische Sitzung. Das Hinzufügen eines Connectors zu einer bereits laufenden Sitzung macht seine Tools auch nicht für Claude verfügbar; starten Sie eine frische Sitzung, um einen neu hinzugefügten Connector aufzugreifen.
• Wenn jemand eine Sitzung archiviert oder löscht oder ihren Runner über das Menü der Sitzung freigibt: Verlassen Sie sich nicht auf den Push durch --push-outcome-on-release. Um Commits in diesen Fällen zu sichern, pushen Sie HEAD aus einem post-session-Hook in einen Rettungs-Branch. Wenn Sie vom dortigen Beispiel ausgehen, sorgen Sie dafür, dass es auch dann pusht, wenn nichts uncommittet ist, da es nur nach einem Snapshot-Commit pusht.

​

Melden Sie ein Problem

​

Fehlerbehebung

claude self-hosted-runner doctor

• Runner erscheint nicht in der Umgebung: Bestätigen Sie, dass der Host api.anthropic.com über HTTPS erreichen kann, das Umgebungsgeheimnis aktuell ist und die Host-Uhr innerhalb von fünf Minuten der echten Zeit liegt; größere Abweichung verursacht, dass die Authentifizierung fehlschlägt. Der Runner protokolliert [runner:fatal] mit dem Ablehnungsgrund bei Auth-Fehler.
• Runner beendet sich beim Start mit cannot create or write to base directory: Der Runner kann --base-dir nicht erstellen oder schreiben, das standardmäßig auf /workspace ist. Beheben Sie das Verzeichnis’s Eigentum oder zeigen Sie --base-dir auf einen beschreibbaren Pfad, wie in Halten Sie das Basis-Verzeichnis und die Kapazität über Runner identisch beschrieben. Wenn der Runner stattdessen [runner:fatal] protokolliert, dass die Basis-Verzeichnis-Überprüfung abgelaufen ist, ist das Verzeichnis auf einem hängenden NFS- oder CSI-Mount. Überprüfen Sie die Mount-Gesundheit anstatt der Berechtigungen. Der Runner druckt beide dieser Startup-Fehler zu stderr, bevor er --log-file öffnet, daher suchen Sie nach ihnen im Terminal oder Ihren Plattform-Container-Logs anstatt der Log-Datei. Vor v2.1.225 überprüfte der Runner das Basis-Verzeichnis nicht beim Start, und diese Fehlkonfiguration schlug Sitzungen nach der Aufnahme fehl.
• Runner beendet sich beim Start mit RegisterRunner failed: und einem TLS-Zertifikatsfehler: Der Fehler kann zum Beispiel self signed certificate in certificate chain lauten. Der Runner vertraut der Zertifizierungsstelle (CA) hinter dem empfangenen Zertifikat nicht, wie es hinter einem TLS-inspizierenden Proxy vorkommt. Setzen Sie NODE_EXTRA_CA_CERTS in der Umgebung des Runners auf eine PEM-Datei mit der Root-CA des Proxys. Für Sitzungen müssen Sie die Variable nicht erneut setzen, da diese sie erben. Git liest sie nicht: Für Clones über diesen Proxy setzen Sie zusätzlich GIT_SSL_CAINFO.
• Ihr Startskript gibt einen Schreibfehler mit Resource temporarily unavailable aus und beendet sich: Ihr Skript teilt seine stdout oder stderr mit dem Prozess claude self-hosted-runner oder Orchestrator, den es startet, und dieser Prozess hat die gemeinsame Pipe bzw. den gemeinsamen Socket in den nicht blockierenden Modus umgeschaltet. Wenn die Pipe voll ist, schlägt ein Schreibvorgang Ihres Skripts mit diesem Betriebssystemfehler fehl, anstatt zu warten, und unter set -e beendet sich das Skript. Um den Fehler zu vermeiden, leiten Sie die Ausgabe des Runners oder Orchestrators in eine Datei um, die der Benutzer Ihres Skripts erstellen kann. Hängen Sie >> "$HOME/claude-runner.log" 2>&1 an den Befehl an, der ihn startet, und zwar vor einem eventuellen &, das ihn in den Hintergrund schickt:
  claude self-hosted-runner --environment-secret-file /etc/claude/environment-secret >> "$HOME/claude-runner.log" 2>&1
  
  Die eigene Ausgabe Ihres Skripts geht weiterhin dorthin, wohin sie vorher ging, während das, was der Runner nach stdout und stderr schreibt, einschließlich seiner Startfehler, in diese Datei geht. Verwenden Sie diese Shell-Umleitung statt --log-file allein, das das Log in eine Datei spiegelt, während der Runner weiterhin nach stdout und stderr schreibt. Wenn Sie bereits --log-file übergeben, behalten Sie es ebenfalls bei, denn die Umleitung ändert nicht, was diese Datei empfängt.
• Orchestrator protokolliert poll failed: mit einem TLS-Zertifikatsfehler und versucht es fortlaufend erneut: Der Orchestrator vertraut der CA hinter dem empfangenen Zertifikat nicht, wie es hinter einem TLS-inspizierenden Proxy vorkommt. Setzen Sie NODE_EXTRA_CA_CERTS in der Umgebung des Orchestrators auf eine PEM-Datei mit der Root-CA des Proxys. Setzen Sie die Variable auch für die Runner, die Ihr spawn-runner-Hook startet. Zum Beispiel kann eine Zeile mit poll failed: self signed certificate in certificate chain — retrying in 1s enden, wobei zwischen dem Doppelpunkt und dem Gedankenstrich die Worte der TLS-Bibliothek stehen. Um die Behebung zu bestätigen, prüfen Sie, dass connected im Body von /healthz des Orchestrators true ist.
• Sitzungen bleiben in der Warteschlange: Jeder Online-Runner kann auf einen anderen Owner gesperrt sein. Überprüfen Sie die claude_code_self_hosted_runner_locked_account-Metrik jedes Runners oder das locked_account-Feld seiner [runner:health]-Log-Zeile, um zu sehen, wer sie hält. Beide zeigen die Email des Owners nur, nachdem der Runner ein Sitzungs-Token mit einem act.email-Claim ausgestellt bekommen hat, das die Sitzungen eines Claude Tag-Agenten niemals tun. Ohne den Claim sendet der Runner keine locked_account-Serie aus und protokolliert locked_account=yes, was Ihnen sagt, dass der Runner gesperrt ist, aber nicht auf welchen Owner. Fügen Sie Replicas hinzu, oder warten Sie, bis ein bestehender Runner drainiert und neu startet. Wenn die Umgebung On-Demand-Runner verwendet, überprüfen Sie stattdessen den Orchestrator; siehe On-Demand-Runner.
• Sitzungen schlagen sofort nach der Aufnahme fehl: Öffnen Sie die Sitzung in claude.ai/code, um den Fehler zu sehen. Wenn der Fehler zeigt, dass Git sich nicht authentifizieren konnte, überprüfen Sie die Git-Anmeldedaten des Runners. Bei einem Runner, der mit --use-anthropic-git-proxy gestartet wurde, siehe Wenn Sitzungen auf einem Runner mit dem Git-Proxy nicht starten. Ein nicht beschreibbares Basis-Verzeichnis stoppt den Runner beim Start, anstatt Sitzungen fehlschlagen zu lassen. Siehe den Runner beendet sich beim Start mit cannot create or write to base directory-Eintrag in dieser Liste.
• Eine Sitzung wird aufgenommen, aber Claude beantwortet ihre erste Nachricht nie: Wenn Ihre Runner api.anthropic.com über einen Proxy erreichen, konfigurieren Sie ihn so, dass er die /worker/events/stream-Antwort der Sitzung so durchreicht, wie sie eintrifft. Das Erhöhen der Timeouts des Runners hilft nicht. Um die Ursache im Log des Runners zu bestätigen, siehe Eine Sitzung wird aufgenommen, aber Claude beantwortet ihre erste Nachricht nie.
• Sitzungen starten nicht auf einem Runner, der --use-anthropic-git-proxy gesetzt hat: Suchen Sie im Log des Runners nach access denied by the git proxy oder nach einem Git-Fehler, der eine api.anthropic.com-Adresse mit /git_proxy/ nennt. Um festzustellen, ob Anthropic die Sitzung bedient hat, und die Ursache zu beheben, siehe Wenn Sitzungen auf einem Runner mit dem Git-Proxy nicht starten.
• Sitzungen können das Netzwerk nicht durch einen authentifizierenden Egress-Proxy erreichen: Wenn die Quelle, die Sie mit --proxy-authorization-command oder --proxy-authorization-file setzen, fehlschlägt, nach 30 Sekunden abläuft oder einen leeren Wert ergibt, antwortet der Runner dieser Verbindung 502 Bad Gateway und protokolliert warum. Der Runner redigiert das Kommando’s stderr in diesem Log und protokolliert niemals den Header-Wert. Mit --proxy-authorization-command führen Sie das Kommando selbst auf dem Host aus, um zu bestätigen, dass es den ganzen Header-Wert auf stdout druckt. Wenn der Runner stattdessen beim Start mit could not start the proxy-authorization listener beendet wird, konnte er seinen Loopback-Listener nicht öffnen.
• Runner protokolliert Poll failed-Zeilen, die rejecting the malformed poll response enthalten: Der Runner erhielt eine Work-Poll-Antwort, deren Body nicht das erwartete JSON der Warteschlange ist. Eine mögliche Ursache ist ein abfangender Proxy oder ein Captive Portal, der mit seiner eigenen Seite antwortet. Wenn sich der Runner über einen Proxy verbindet, konfigurieren Sie den Proxy so, dass er Antworten von api.anthropic.com unverändert durchlässt. Der Runner lehnt die fehlerhafte Antwort ab, zählt sie unter der transport-Art der claude_code_self_hosted_runner_poll_errors_total-Metrik und versucht es gemäß dem Zeitplan für fehlgeschlagene Polls, der in Sitzungs-Lebenszyklus beschrieben ist, erneut. Der Runner bedient weiterhin seine Live-Sitzungen. Vor v2.1.246 las der Runner eine solche Antwort als eine leere Warteschlange, die seine Live-Sitzungen beenden oder ihn zum Exit bringen könnte.
• Eine Sitzung schlägt mit no longer exists on the remote oder couldn't find remote ref fehl: Der Runner wertet das couldn't find remote ref von Git als gelöschten Branch. Der Branch kann trotzdem noch existieren. Suchen Sie ihn auf Ihrem Git-Host unter genau dem Namen aus der Meldung, und prüfen Sie dann jede zutreffende Ursache:
  • Der Branch ist weg: Stellen Sie ihn wieder her, wie die Meldung es verlangt.
  • Der Branch existiert und Sie administrieren den Runner nicht: Senden Sie dem Administrator des Runners die vollständige Meldung und teilen Sie ihm mit, dass der Branch existiert.
  • Der Branch existiert und der Runner hat einen checkout-Hook: Ein Git-Befehl in Ihrem Hook kann couldn't find remote ref nach stderr ausgeben, bevor der Hook mit einem Exit-Code ungleich null endet. Finden Sie diesen Befehl, und korrigieren Sie die Ref, die er anfordert, oder das Remote, von dem er abruft. Der Runner übergibt Ihrem Hook die von der Sitzung angeforderte Revision als CLAUDE_RUNNER_REPO_REF.
  • Der Branch existiert und der Runner hat keinen checkout-Hook: Der Runner ruft den Branch selbst ab. Wenn ein --git-host-rewrite für das Repository gilt, prüfen Sie, ob der Host, auf den umgeschrieben wird, den Branch unter demselben Namen hat, und pushen Sie den Branch dorthin, falls nicht.
  • Der Branch existiert und der Runner ist älter als v2.1.301: Aktualisieren Sie den Runner wie in Version festlegen beschrieben, damit ein anderer Fehler seine eigene Fehlermeldung anzeigt. Vor v2.1.301 wurden auch andere Fehler mit couldn't find remote ref in ihrer Fehlerausgabe als gelöschter Branch gemeldet.
  Sobald der Runner aktualisiert oder die Ursache behoben ist, versuchen Sie die Sitzung erneut oder starten Sie eine neue. Wenn keine dieser Prüfungen die Ursache findet, melden Sie ein Problem. Bei der Quelle, zu der die Sitzung Ergebnisse pusht, lässt ein gelöschter Branch die Sitzung fehlschlagen. Bei einer Git-Quelle, die die Sitzung nur liest, überspringt der Runner diese Quelle und setzt auf den verbleibenden fort. Der Runner lässt die Sitzung fehlschlagen, wenn das Überspringen sie ohne jedes Repository zurücklassen würde. Vor v2.1.228 startete eine solche Sitzung in einem leeren Verzeichnis.
• Claude Tag postet seine Antwort in Slack manchmal nicht: Die Antwort-Erinnerung ist ein Hook, den die Control Plane bereitstellt. Prüfen Sie mit claude --version, ob der Runner Claude Code v2.1.229 oder neuer ist, da ältere Runner bereitgestellte Hooks ignorieren; prüfen Sie, ob python3 --version im Runner-Image erfolgreich ausgeführt wird, da die Hooks python3 ausführen; und prüfen Sie, dass keine Einstellungsdatei Hooks ausschaltet, sei es disableAllHooks in managed-settings.json, in der ~/.claude/settings.json des Runner-Benutzers oder in der .claude/settings.json oder .claude/settings.local.json des Repositorys, oder allowManagedHooksOnly oder eine strictPluginOnlyCustomization in den verwalteten Einstellungen, die Hooks abdeckt.
• Eine Sitzung startet ohne eines ihrer Repositories: Auf einem Runner ohne checkout Hook kann der Git-Host den Zugriffsprüfung des Runners für ein Repository, das die Sitzung nur liest, ablehnen. Der Runner überspringt dann dieses Repository, protokolliert eine [runner:warn] could not access context source-Zeile, die die Ablehnung benennt, und startet die Sitzung auf den verbleibenden. Der Runner überspringt nur eine klare Ablehnung: Der Host antwortet, dass das Repository nicht gefunden wurde, Git findet keine Anmeldedaten für den Host, oder die Authentifizierung schlägt fehl. Ein Netzwerkfehler, ein Timeout oder ein HTTP 403 schlägt immer noch den Sitzungsstart fehl, ebenso wie eine Ablehnung für ein Repository, zu dem die Sitzung Ergebnisse pusht. Der Runner schlägt immer noch eine Sitzung fehl, die das Überspringen ohne Repository überhaupt verlassen würde. Mit --use-anthropic-git-proxy überspringt der Runner nur ein Repository, das der Git-Proxy selbst ablehnt. Die Zugriffsprüfung läuft jedes Mal erneut, wenn die Sitzung auf einem Runner startet, daher sobald die Git-Identität des Runners Lesezugriff hat, klont der nächste Start das Repository. Vor v2.1.274 schlugen jede dieser Ablehnungen den Sitzungsstart fehl.
• Eine Sitzung startet nicht mit This runner couldn't read: Der Runner hat den Git-Host mit seinen Git-Anmeldedaten nach einem Repository gefragt und die Antwort erhalten, dass es nicht gefunden wurde. Das Repository existiert nicht, oder diese Anmeldedaten können das Repository nicht erreichen.
  • Wenn Sie den Runner administrieren: Gewähren Sie seinen Git-Anmeldedaten Lesezugriff auf das Repository, und starten Sie dann eine neue Sitzung.
  • Wenn Sie die Sitzung gestartet haben: Wenn das Repository nicht existiert, starten Sie eine neue Sitzung mit dem richtigen Repository. Wenn der Runner das Repository nicht erreichen kann, bitten Sie den Administrator des Runners, Zugriff zu gewähren, und starten Sie dann eine neue Sitzung.
• Sitzungen brauchen Minuten zum Starten oder Fortsetzen: Eine Ursache ist ein frischer Clone. In einer Flotte, die jeden Runner auf einer leeren Festplatte startet, ohne checkout-Hook, klont der Runner die Repositorys der Sitzung neu, bevor er Claude Code startet. Eine Sitzung, die auf einer leeren Festplatte fortgesetzt wird, wartet erneut auf denselben Clone. Um den frischen Clone zu überspringen, stellen Sie einen vorgewärmten Checkout bereit. Wenn Sie bereits einen bereitstellen, bestätigen Sie, dass der Runner ihn verwendet. Wo der Runner den Clone selbst erstellt und sich nach einer Sitzung beendet, senken Sie CLAUDE_RUNNER_FETCH_DEPTH von seinem Standardwert von 50 Commits, um weniger Verlauf abzurufen. Wenn Sie einen Hook verwenden, läuft er anstelle des Clones des Runners, prüfen Sie also stattdessen, was Ihr Hook tut. Beobachten Sie die claude_code_self_hosted_runner_session_init_duration_seconds-Metrik, um zu sehen, wie lange Starts dauern.
• Turns schlagen mit einem 401 fehl: Wenn ein Turn mit einem 401 oder 403 von der Anthropic API endet, ruft der Runner ein frisches CLAUDE_CODE_OAUTH_TOKEN von Anthropic ab und übergibt es der Sitzung. Der fehlgeschlagene Turn wird nicht erneut versucht. Dieses Token ist kurzlebig, und der Runner rotiert es über die stdin der Sitzung. Wenn ein Abruf fehlschlägt, protokolliert der Runner eine inference_token refresh failed-Zeile, die sagt, wann er erneut versuchen wird, und er versucht es weiterhin erneut, solange die Sitzung läuft. Wenn jeder Aufruf etwa 30 Minuten in eine Sitzung hinein fehlschlägt, hat ein Wrapper-Skript wahrscheinlich die Sitzungs-stdin unterbrochen, daher können Token-Rotationen sie nicht erreichen; siehe Halten Sie stdin und Dateideskriptor 3 angehängt. Vor v2.1.274 stoppte der Runner das erneute Versuchen eines fehlgeschlagenen Abrufs nach einigen Versuchen und wartete auf den nächsten geplanten. Ein fehlgeschlagener Turn löste keinen Abruf aus, daher schlugen alle Turns mit einem 401 fehl, bis zum nächsten geplanten Abruf.
• Ein Turn schlägt in claude.ai/code mit This model needs a newer version of Claude Code fehl: Die Claude Code-Version, mit der Ihre Runner Sitzungen starten, ist älter, als das Modell der Sitzung erfordert, daher lehnt die API die Anfrage ab. Aktualisieren Sie die Runner auf die Version, die die Meldung verlangt, oder auf eine neuere, wie in Version festlegen beschrieben. Bis dahin können Benutzer in der Sitzung ein anderes Modell auswählen.
• Pod wird Mid-Drain getötet: Erhöhen Sie terminationGracePeriodSeconds auf mindestens den Wert, den der Runner beim Start protokolliert. Siehe Shutdown-Timing.

​

Wenn der Runner beendet wird

• Ein normaler Exit: Der Runner hat seine Sitzungen beendet und drainiert, seine Ruhezeit erreicht oder wurde angewiesen zu stoppen. Starten Sie ihn neu, damit die Umgebung wieder Kapazität hat. Runner-Lebenszyklus beschreibt diese Exits.
• Ein fehlgeschlagener Start: Der Runner kann nicht mit der Konfiguration oder dem Host starten, der ihm gegeben wurde, daher beendet er sich Sekunden nach dem Start, und er beendet sich jedes Mal auf die gleiche Weise, wenn Sie ihn neu starten. Ein schnellerer Neustart hilft nicht. Jemand muss seine Ausgabe lesen und die Ursache beheben.
• Verlorener Kontakt: Ein Runner, der Anthropic länger als seinen Lease nicht erreichen kann, zum Beispiel während sein Host schläft, kann aus der Umgebung entfernt werden. Wenn sich ein entfernter Runner wieder verbindet, beendet er sich. Sein Log kann eine [runner:fatal]-Zeile zeigen, die runner record gone server-side oder, nach einem längeren Ausfall, poll auth failed enthält. Der Runner registriert sich nicht von selbst erneut, starten Sie ihn also neu.

​

Erkennen Sie einen fehlgeschlagenen Start

[runner:fatal] --use-anthropic-git-proxy requires --capacity 1 (the proxy URL is per-session and linked worktrees share origin). Omit --use-anthropic-git-proxy or set --capacity 1.

• Keine Zeile überhaupt: Ein Runner, den der Host tötet, druckt keine. Wenn die Ausgabe mit keiner [runner:fatal]-Zeile und keiner error:-Zeile endet, überprüfen Sie, ob der Host oder Ihr Orchestrator den Prozess gestoppt hat, zum Beispiel für das Überschreiten eines Speicherlimits.
• Der Exit-Code: Der Runner setzt keinen Exit-Code für Fehler beiseite, die bei jedem Start wiederholt werden. Er beendet sich mit dem gleichen Code für einen Konfigurationsfehler, wie eine nicht unterstützte Kombination von Flags, und für einen Fehler, der sich selbst löschen kann, wie die API, die durch die eigenen Wiederholungen des Runners unerreichbar bleibt. Basieren Sie die Entscheidung, länger zu warten, darauf, wie schnell der Runner beendet wurde, und lesen Sie die Ausgabe des Runners, um zu erfahren warum.
• Eine Umgebung, die gesund aussieht: Einige Startup-Schritte laufen, nachdem sich der Runner bei Ihrer Umgebung registriert hat, wie --configure-git und die Credential-Einrichtung des Anthropic Git-Proxy. Wenn einer dieser Schritte fehlschlägt, kann die Umgebung diesen Runner für ein paar Minuten nach dem Prozessende weiterhin auflisten, und die Cloud-Umgebungen-Seite kann Gesund lesen, während kein Runner Arbeit aufnimmt. Wenn Sitzungen in einer Umgebung, die gesund aussieht, in der Warteschlange bleiben, überprüfen Sie, ob Ihr Supervisor den Runner neu startet.

​

Neustart mit einer wachsenden Wartezeit

• Kubernetes: Die Deployment auf dieser Seite benötigt keine Änderung. Nachdem ein Container beendet wird, wartet das kubelet standardmäßig, bevor es den Container neu startet, und die Wartezeit wächst bei jedem Neustart bis zu einer Obergrenze. Die Wartezeit startet von vorne, sobald der Container eine Weile ohne Beendigung läuft. Das kubelet wendet die gleiche Wartezeit nach einem normalen Exit an, wenn der Container nur kurz lief. Ein Runner, der oft drainiert, kann daher auch den CrashLoopBackOff-Status zeigen, daher lesen Sie die Ausgabe, bevor Sie schließen, dass der Runner nicht starten kann. Der Befehl unten liest die letzte Lauf-Ausgabe von einem Pod der Deployment:
  kubectl logs --previous -n claude-runners deploy/claude-runner
  
  Wenn der letzte Lauf ein fehlgeschlagener Start war, ist die [runner:fatal]- oder error:-Zeile unter den letzten Zeilen der Ausgabe. Um die letzte Lauf eines anderen Pods zu lesen, benennen Sie diesen Pod anstelle von deploy/claude-runner.
• Docker und Docker Compose: Die Compose-Rezept auf dieser Seite benötigt keine Änderung. Mit restart: always wartet Docker länger vor jedem Neustart eines Containers, der weiterhin beendet wird, bis zu einer Obergrenze. Ersetzen Sie <container> mit dem Namen des Containers im Befehl unten, der liest, wie oft Docker den Container neu gestartet hat:
  docker inspect --format '{{.RestartCount}}' <container>
  
  Der Befehl druckt eine Zahl. Eine Zahl, die weiterhin klettert, bedeutet Docker startet den Runner weiterhin neu.
• Eine systemd-Unit: Standardmäßig wartet systemd die gleiche RestartSec vor jedem Neustart und verlängert sie nicht, daher startet eine Unit mit Restart=always einen Runner, der nicht starten kann, in diesem gleichen Intervall jedes Mal neu. Wenn die Starts schnell genug kommen, um die Start-Rate-Grenze der Unit zu erreichen, fünf Starts in 10 Sekunden standardmäßig, stoppt systemd das Neustarten der Unit. Die Unit bleibt gestoppt, bis jemand sie wieder startet, was systemd erlaubt, sobald das Intervall der Rate-Grenze vergangen ist oder nach systemctl reset-failed. Weil RestartSec auf jeden Neustart angewendet wird, verzögert ein längerer Wert auch den Neustart nach einem normalen Exit. Wählen Sie einen Wert, der die beiden ausgleicht, und warnen Sie bei der Neustart-Zählung der Unit.
• Eine Shell-Schleife oder Ihr eigener Supervisor: Wenden Sie die gleiche Regel selbst an. Beginnen Sie mit einer Wartezeit von fünf Sekunden. Nach jedem Lauf, der innerhalb einer Minute endete, verdoppeln Sie die Wartezeit für den nächsten Neustart, bis zu fünf Minuten. Nach einem Lauf, der eine Minute oder länger dauerte, gehen Sie zurück zu fünf Sekunden.

​

Überprüfen Sie, warum der Runner weiterhin beendet wird

• Die letzte [runner:fatal]- oder error:-Zeile: Sie sagt, warum der Runner gestoppt wurde. Fehlerbehebung listet die häufigen Ursachen auf.
• Die Kombination von Flags: Der Anthropic Git-Proxy erfordert --capacity 1. Die Rezepte auf dieser Seite verwenden eine höhere Kapazität, daher senken Sie sie, wenn Sie den Proxy zu einem von ihnen hinzufügen.
• Was die Umgebung des Service erreichen kann: Wenn der Runner von Hand startet und unter Ihrem Supervisor fehlschlägt, vergleichen Sie den Benutzer, das Home-Verzeichnis, den PATH und das Speicherlimit. --configure-git und der Anthropic Git-Proxy benötigen Git auf dem PATH und ein beschreibbares ~/.gitconfig.
• Das Umgebungsgeheimnis: Wenn Sie das Geheimnis widerrufen oder falsch eingegeben haben, druckt der Runner eine Zeile, die RegisterRunner auth failed enthält.
• Die Aktivitäts-Registerkarte der Umgebung: Öffnen Sie die Umgebung und wählen Sie Aktivität. Wenn neue Runner dort weiterhin erscheinen und keiner Arbeit aufnimmt, startet Ihr Supervisor den Runner neu.

​

Eine Sitzung wird aufgenommen, aber Claude beantwortet ihre erste Nachricht nie

GET https://api.anthropic.com/v1/code/sessions/<session-id>/worker/events/stream

• Puffern Sie die Antwort nicht: Reichen Sie sie so durch, wie sie eintrifft. Ihr Content-Type ist text/event-stream.
• Lassen Sie die Antwort offen: Sie kann bis zu einer Stunde offen bleiben. Wenn der Proxy einen Leerlauf-Timeout hat, halten Sie ihn deutlich über 15 Sekunden, da Anthropic standardmäßig mindestens so oft ein Keep-alive sendet.

​

Bestätigen Sie die Ursache im Log des Runners

1. Warten Sie, bis --startup-timeout-min abgelaufen ist, standardmäßig 15 Minuten. Der Runner stoppt dann die Sitzung und protokolliert eine Zeile, die no child output for enthält und mit — releasing endet.
2. Durchsuchen Sie das Log des Runners nach SDKStartup: SSE. Diese Zeilen folgen auf eine finished: interrupted-Zeile, einige Zeilen nach der aus Schritt 1. Die meisten haben keinen Zeitstempel, daher zeigt ein Log-Collector sie möglicherweise an anderer Stelle an.
3. Suchen Sie die Zeile in dieser Tabelle:

​

Verhindern Sie, dass die Sitzung es erneut versucht

​

Was kommt als nächstes

• Passen Sie Sitzungen an: Wrapper-Skripte, Lebenszyklus-Hooks, On-Demand-Runner, MCP-Server und Berechtigungen
• Testen Sie End-to-End: Überprüfen Sie ein neues Runner-Image von CI, bevor Sie es fördern
• Referenz: Jedes CLI-Flag, jede Umgebungsvariable und jede Metrik