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.
• 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. Für den anfänglichen Clone, der vor dem Ausführen des Wrappers stattfindet, verwenden Sie einen checkout-Lebenszyklus-Hook oder --use-anthropic-git-proxy; siehe Git konfigurieren.
• 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

​

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.

​

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

​

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, Umschreiben von https://<host>/owner/repo zu git@<host>:owner/repo

​

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 \
 && 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=2.1.224 -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.

​

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"
          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"
    secrets:
      - environment-secret
    restart: always
    stop_grace_period: 90s

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

​

Shutdown-Timing

• Mit einer SIGTERM-Grace-Periode: Setzen Sie terminationGracePeriodSeconds auf Kubernetes, stop_grace_period auf Docker Compose oder das Äquivalent Ihres Orchestrators auf mindestens dieses Gesamte. Der Kubernetes-Standard von 30 Sekunden ist kürzer als der Drain-Pfad des Runners, daher stoppt Kubernetes den Pod, bevor der Runner fertig drainiert.
• Mit --retire-at: Dimensionieren Sie die Marge zwischen der Retire-Zeit und der Host-Stop-Zeit, um typische Turns zu decken, plus den Background-Task-Hold, den Runner-Lebenszyklus beschreibt, plus dieses gleiche Gesamte. Berechnen Sie die Retire-Zeit bei jedem Launch, zum Beispiel date +%s plus die beabsichtigte Lebensdauer des Runners.
• Mit --defer-shutdown-max-min: Fügen Sie zwei weitere Teile zum Drain-Pfad-Gesamte hinzu. Der erste ist die Minuten, die Sie konfigurieren. Der zweite ist die Post-Release-Grace, die Defer the drain past the first signal beschreibt, 75 Sekunden bei Defaults. Mit dem Flag gesetzt, druckt der Runner auch die kombinierte Zahl beim Start, nach dem Drain-Pfad-Gesamte.

​

Verschieben Sie den Drain über das erste Signal hinaus

​

Was mit den Sitzungen passiert, die der Runner nach dem ersten Signal hält

• Für die ersten n Minuten: Der Runner bedient seine Sitzungen normal und erzwingt weiterhin --startup-timeout-min und --kill-session-after-min. Wenn Sie auch --release-idle-session-min setzen, gibt der Runner jede Sitzung frei, deren Benutzer so lange untätig war; ohne es gibt der Runner keine Sitzung früh frei, außer einem Startup-Timeout.
• Wenn die n Minuten ablaufen: Der Runner gibt jede Sitzung frei, die er noch hält, untätig oder nicht. Der Runner wartet auf die Turn einer Mid-Turn-Sitzung, um zu enden, und bis zu 60 Sekunden mehr für die Background-Tasks einer Turn, bevor er diese Sitzung freigibt.
• Wenn die Post-Release-Grace abläuft: Der Runner drainiert alle Sitzungen, die er noch hält, und die Kontrollebene requeued jede drainierte Sitzung sofort zu einem anderen Runner. Die Post-Release-Grace startet, wenn die n Minuten ablaufen und ist 75 Sekunden bei Defaults. Wenn Sie --drain-wait-sec über 60 Sekunden setzen, ist die Post-Release-Grace --drain-wait-sec plus 15 Sekunden stattdessen.

​

Dimensionieren Sie das Stop-Timeout

​

Was einen laufenden Post-Session-Hook erreicht

• Ein SIGTERM, während der Runner bereits drainiert: Beendet den Runner sofort mit Gewalt, überspringt alles, was vom Drain-Pfad bleibt. Ohne --defer-shutdown-max-min ist das das zweite SIGTERM, das der Runner erhält. Nichts signalisiert einen laufenden post-session-Hook, daher auf einem bloßen Host, wo ein Init-Prozess Waisen adoptiert, beendet er sich selbst, aber unüberwacht: sein Timeout-Budget gilt nicht mehr, und ein Schreiben in die geschlossene Log-Pipe kann ihn mit SIGPIPE töten, daher sollte ein Hook, der einen erzwungenen Exit dort überleben muss, seine eigene Ausgabe zu einer Datei umleiten. In den Container-Rezepten auf dieser Seite ist der Runner der Container’s PID 1 und sein Exit beendet den Container, und unter systemd’s Standard KillMode=control-group erreicht die Cgroup-weite Kill den Hook auch, wie der Cgroup-weite Kills-Eintrag beschreibt; in beiden behandeln Sie einen erzwungenen Exit als tödlich für den Hook und verlassen sich stattdessen auf die Grace-Periode.
• Prozessgruppen-weite Signale, wie kill -- -<pid> in einem Wrapper-Skript, Shell-Job-Kontrolle oder ein Gruppen-weiter Watchdog: erreichen den Runner und einen Mid-checkout-Hook-Subprozess, der absichtlich Gruppen-angehängt bleibt, aber nicht einen laufenden post-session-Hook oder das Sitzungs-Kind.
• Cgroup-weite Kills, wie systemd’s Standard KillMode=control-group oder die SIGKILL, die Kubernetes dem ganzen Container liefert, wenn terminationGracePeriodSeconds abläuft: erreichen alles, einschließlich des Hooks. Prozessgruppen-Isolation schützt nicht gegen diese, weshalb die Grace-Periode den vollständigen Drain-Pfad decken muss.
• Das Timeout des Hooks selbst: Wenn ein Hook --post-session-hook-timeout-sec überschreitet, sendet der Runner SIGTERM zur ganzen Prozessgruppe des Hooks, dann SIGKILL zwei Sekunden später, daher beendet sich ein Worker, den der Hook forked, wie tar, rsync oder git, mit der Wrapper-Shell anstatt als Waise zu überleben. Die Überwachung des Runners endet, sobald das Hook’s stdio schließt: ein Worker, der seine eigene Ausgabe zu einer Datei umgeleitet hat und die SIGTERM-Phase überlebt, ist jenseits der Reichweite des Runners.

​

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

​

Wiederverwendung eines vorgewärmten Checkouts

• 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.

• Jede Klonform funktioniert: Ein vollständiger, flacher oder Single-Branch-Klon unter dem Pfad wird unverändert verwendet. Der Runner übergibt niemals --depth beim Abrufen in einen vorhandenen Klon, daher behält ein vollständiger Vorwärm seine vollständige Historie und ein flacher bleibt flach. CLAUDE_RUNNER_FETCH_DEPTH (full, 0 oder eine Zahl; Standard 50) steuert nur den kalten Klon, den der Runner erstellt, wenn noch kein Klon vorhanden ist.
• Nachverfollgte Änderungen werden zurückgesetzt, nicht nachverfolgte Dateien bleiben erhalten: Jede Sitzung beginnt mit einem harten Zurücksetzen, das die verfolgten Ä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.
• 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, behält den Objektspeicher, Referenzen und den flachen Zustand, löscht aber den Index, sodass jede Sitzung einen vollständigen Working-Tree-Checkout anstelle eines nahezu augenblicklichen Zurücksetzen zahlt; es wird immer noch nie neu geklont. Submodul-Vorwärme wird unter dem Proxy nicht unterstützt.
• 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.

​

Pinnen Sie die Version

• 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 zu upgraden: Installieren Sie die neuere Version oder erstellen Sie das Image neu, dann starten Sie die Runner neu
• 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.

​

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

​

Zusätzliche Einschränkungen

• Fortgesetzte Sitzungen verlieren unpushed Arbeit: Wenn eine Sitzung freigegeben wird, bei Untätigkeits-Timeout oder Runner-Neustart, und der Benutzer sendet eine weitere Nachricht, setzt sich die Sitzung auf einem frischen Runner fort, der das Repository erneut von seinem Starting-Branch klont, daher ist Arbeit, die die Sitzung nicht gepusht hat, weg. Setzen Sie --push-outcome-on-release, um den Runner einen Best-Effort-Push der Sitzungs-Outcome-Branches vor der Freigabe machen zu lassen, daher startet die fortgesetzte Sitzung von diesen Commits; dies bewahrt committed Arbeit, nicht einen Dirty Working Tree. Bevor Sie es aktivieren, beschränken Sie, wer zu claude/*-Refs auf dem Source-Remote pushen kann, zum Beispiel mit einem Branch-Ruleset: Bei Resume ruft der Runner den zuvor gepushten Branch ab, ohne zu überprüfen, wer ihn gepusht hat, daher kann jeder mit Push-Zugriff zu diesen Refs Inhalt in den fortgesetzten Workspace platzieren. Der Runner verwirft auch Pro-Sitzungs-Konfiguration bei Resume, was das Claude-Konfigurationsverzeichnis der Sitzung und jeden Shell-Zustand bedeutet, den die Sitzung schrieb; --push-outcome-on-release deckt diese nicht ab.
• Private Repositorys können nicht Mid-Sitzung hinzugefügt werden: Ein Repository, das zu einer Sitzung hinzugefügt wird, nachdem es gestartet hat, wird nicht mit Anmeldedaten auf einem selbstgehosteten Runner geklont, daher schlägt das Hinzufügen fehl. Wählen Sie jedes Repository, das die Sitzung benötigt, wenn Sie es erstellen.
• 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.

​

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.
• 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. Die häufigsten Ursachen sind fehlende Git-Anmeldedaten im Runner-Image und Build-Tools, die nicht installiert sind. Ein nicht beschreibbares Basis-Verzeichnis stoppt den Runner beim Start anstatt Sitzungen zu fehlschlagen. Siehe den Runner beendet sich beim Start mit cannot create or write to base directory-Eintrag in dieser Liste.
• 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, am häufigsten weil etwas zwischen dem Runner und api.anthropic.com, wie ein abfangender Proxy oder ein Captive Portal, seine eigene Seite antwortet. Der Runner lehnt die Antwort ab, zählt sie unter der transport-Art der claude_code_self_hosted_runner_poll_errors_total-Metrik, und versucht erneut auf dem fehlgeschlagenen Poll-Plan, der in Sitzungs-Lebenszyklus beschrieben ist. Der Runner bedient weiterhin seine Live-Sitzungen. Konfigurieren Sie den Proxy, um Antworten von api.anthropic.com unverändert durchzulassen. 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.
• Ein Sitzungs-Branch existiert nicht mehr auf dem Remote: Für eine Git-Quelle, die die Sitzung nur liest, überspringt der Runner diese Quelle und setzt auf den verbleibenden fort. Für die Quelle, zu der die Sitzung Ergebnisse pusht, schlägt ein gelöschter Branch, typischerweise weil er gemergt und auto-gelöscht wurde, die Sitzung mit einem Fehler fehl, der das Repository und den Branch benennt und Sie auffordert, den Branch wiederherzustellen und erneut zu versuchen. Der Runner schlägt die Sitzung mit dem gleichen Fehler fehl, wenn das Überspringen sie mit keinem Repository überhaupt verlassen würde. Vor v2.1.228 startete eine solche Sitzung in einem leeren Verzeichnis.
• Sitzungen dauern Minuten zum Start: Der anfängliche Clone dominiert normalerweise. Beobachten Sie die claude_code_self_hosted_runner_session_init_duration_seconds-Metrik, um zu bestätigen, und schneiden Sie den Clone mit einem vorgewärmten Checkout oder einem kleineren CLAUDE_RUNNER_FETCH_DEPTH.
• Pod wird Mid-Drain getötet: Erhöhen Sie terminationGracePeriodSeconds auf mindestens den Wert, den der Runner beim Start protokolliert. Siehe Shutdown-Timing.

​

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