Claude Code am eigenen Server: Self-Hosted Runner erklärt

Was der Self-Hosted Runner von Claude Code macht

Wichtig gleich vorweg, weil hier die meisten Missverständnisse entstehen: Der Self-Hosted Runner verlagert die Ausführung auf deinen Server, nicht das Sprachmodell. Die eigentliche Denkarbeit läuft weiterhin über die Anthropic-API. Auf deinem Server passiert alles andere – Dateien lesen und schreiben, Befehle ausführen, Repositories auschecken, Tests laufen lassen.

Betroffen sind ausschließlich Cloud-Sessions. Das sind jene Sitzungen, die nicht am Rechner der Entwicklerin oder des Entwicklers laufen, sondern im Hintergrund weiterarbeiten: gestartet über claude.ai, die Apps für Mobilgerät und Rechner, geplante Routinen oder das Terminal per claude --cloud. Wer Claude Code nur klassisch im Terminal nutzt, braucht hier nichts einzurichten – diese Sitzungen laufen ohnehin schon lokal.

Umgebung, Runner und Session – die drei Bausteine

Das Zusammenspiel besteht aus drei Teilen:

Der Ablauf ist unkompliziert: Startet jemand eine Cloud-Session, erscheint eine Auswahl der verfügbaren Umgebungen – die von Anthropic und deine eigenen. Wählt die Person deine Umgebung, legt Anthropic die Aufgabe in eine Warteschlange. Dein Runner holt sie ab, klont das Repository und startet einen Claude-Code-Prozess auf deinem Server.

Alle Verbindungen gehen dabei von deinem Netzwerk nach außen. Anthropic baut keine Verbindung zu dir auf. Der Runner fragt selbst regelmäßig bei api.anthropic.com nach neuer Arbeit, und dieses Nachfragen dient gleichzeitig als Lebenszeichen. Bleibt es rund 60 Sekunden aus, wandert die Session zurück in die Warteschlange und ein anderer Runner übernimmt.

Was auf deinem Server bleibt – und was nicht

Auf deinen Maschinen bleiben: Repository-Kopien, Build-Ergebnisse, Zugangsdaten und sämtliche Dateien, die eine Session anlegt oder verändert.

Zu Anthropic gehen: die Unterhaltung selbst, also Eingaben, Antworten und Werkzeugergebnisse – sie werden für die Modellabfrage gebraucht. Anthropic speichert außerdem das Sitzungsprotokoll, damit du dieselbe Session später auf einem anderen Gerät fortsetzen kannst. Auch die Steuerungsebene bleibt bei Anthropic: Warteschlange, Verteilung und die Oberfläche auf claude.ai.

Für wen sich ein eigener Server für Claude Code lohnt

Ehrlich gesagt: für die meisten Teams nicht. Die von Anthropic betriebenen Umgebungen erfordern keinerlei eigene Infrastruktur, und genau das ist ihr Vorteil.

Ein eigener Server zahlt sich in drei Situationen aus:

• Zugriff auf interne Systeme. Die Sessions laufen in deinem Netzwerk und erreichen interne Datenbanken, Registries und Dienste, ohne dass du irgendetwas ins offene Internet stellst.
• Eigene Werkzeuge. Du baust dein Runner-Abbild selbst und legst Compiler, SDKs und interne Kommandozeilenwerkzeuge gleich mit hinein. Jede Session startet damit einsatzbereit.
• Vorgaben zur Datenhaltung. Auschecken und Bauen passiert auf Infrastruktur, die dir gehört.

Der Preis dafür ist Betriebsverantwortung: Du baust das Abbild, betreibst die Maschinen, hältst sie aktuell und kontrollierst ihren Netzwerkzugang. Das ist eine bewusste Entscheidung, kein Schalter.

Voraussetzungen: Was dein Server mitbringen muss

Ob dein Host bereit ist, prüfst du in einer Zeile:

claude self-hosted-runner --help

Erscheint eine Übersicht mit Optionen wie --environment-secret-file, passt die Version. Kommt stattdessen die allgemeine Hilfe von claude, ist die Installation zu alt.

Zur Ausstattung des Servers: Anthropic nennt keine offiziellen Mindestwerte für Prozessor und Arbeitsspeicher. Was die Last treibt, ist absehbar: das erstmalige Klonen des Repositories, deine Build-Werkzeuge und die Anzahl gleichzeitiger Sessions je Runner. Plane also entlang deiner Projekte, nicht entlang einer Zahl aus einer Anleitung. Ein wichtiger Faktor kommt dazu – siehe der Abschnitt zur Anzahl der Runner weiter unten.

Claude Code am eigenen Server einrichten

Der schnellste Weg ist die geführte Einrichtung. Sie startet eine Claude-Code-Sitzung, die dich durch das Anlegen der Umgebung führt, den Runner startet und eine Kurzanleitung ablegt:

claude self-hosted-runner setup

Dafür musst du auf der Maschine mit claude auth login angemeldet sein, und zwar mit einem Konto, das Inhaber- oder Administratorrechte hat. Auf Servern ohne interaktive Sitzung gehst du manuell vor.

1. Funktion freischalten

Eine Person mit Inhaber- oder Administratorrolle aktiviert Allow self-hosted environments auf der Admin-Seite „Cloud environments” auf claude.ai. Solange das aus ist, gibt es die Schaltfläche zum Anlegen gar nicht. Voraussetzung dafür ist, dass Claude Code on the web für die Organisation freigeschaltet ist.

2. Umgebung anlegen und den Schlüssel sichern

Neue Umgebung anlegen, benennen, erstellen – und im zweiten Schritt den Umgebungsschlüssel kopieren. Dieser Wert wird genau einmal angezeigt und lässt sich später nicht mehr abrufen. Er verfällt 365 Tage nach der Erstellung. Die Kennung der Umgebung im Format ccpool_... bleibt dagegen dauerhaft sichtbar.

Geht der Schlüssel verloren, legst du in der Umgebung einen neuen an, verteilst ihn an deine Runner und ziehst erst dann den alten zurück.

3. Schlüssel ablegen und Runner starten

Den Schlüssel schreibst du so in eine Datei, dass er nicht im Verlauf deiner Kommandozeile landet – einfügen, Enter, dann Strg-D:

mkdir -p /etc/claude
(umask 077 && cat > /etc/claude/environment-secret)

Danach startest du den Runner. Das Arbeitsverzeichnis muss der Benutzer, unter dem der Runner läuft, anlegen und beschreiben können:

claude self-hosted-runner \
  --environment-secret-file '/etc/claude/environment-secret' \
  --base-dir '/srv/claude-workspace'

Ohne --base-dir verwendet der Runner /workspace. Das funktioniert nur, wenn dieses Verzeichnis bereits existiert und beschreibbar ist oder der Runner als root läuft.

4. Prüfen und erste Session schicken

Auf der Admin-Seite wechselt der Zustand deiner Umgebung innerhalb weniger Sekunden von „No runners deployed” auf „Healthy”. Anschließend startest du auf claude.ai/code eine Session und wählst deine Umgebung aus. Der Runner protokolliert Picked up session <session-id> – damit siehst du direkt in der Ausgabe, welcher Host die Aufgabe übernommen hat.

Eine Nachricht an eine laufende Session schickst du von jeder angemeldeten Maschine aus:

claude -p "deine Nachricht" --cloud <session-id>

Den Runner im Container betreiben

Anthropic stellt kein fertiges Runner-Abbild bereit – du baust es selbst und legst genau die Werkzeuge hinein, die deine Projekte brauchen. Ein schlanker Ausgangspunkt:

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}/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 "[email protected]" \
 && git config --system --add safe.directory '*'
ENTRYPOINT ["claude"]

Auf ARM-Maschinen tauschst du linux-x64 gegen linux-arm64, bei Abbildern auf musl-Basis wie Alpine gegen die entsprechende musl-Variante.

Für den Dauerbetrieb brauchst du etwas, das den Runner nach dem Beenden neu startet – Kubernetes, Docker Compose oder ein vergleichbares Werkzeug. Der Runner beendet sich nämlich absichtlich, sobald seine aktiven Sessions fertig sind. Zwei Dinge sind dabei entscheidend:

• Genug Zeit zum Aufräumen. Der geordnete Rückzug braucht bei Standardwerten rund 80 Sekunden, und der Runner protokolliert diesen Wert beim Start. Die 30 Sekunden, die Kubernetes standardmäßig gewährt, reichen nicht und beenden den Container mitten im Aufräumen.
• Gleiche Werte im Verbund. --base-dir und --capacity müssen auf allen Runnern einer Umgebung identisch sein. Sonst zeigen Pfade, die sich Claude in einer Session gemerkt hat, nach einem Wechsel ins Leere.

Für die Überwachung stellt der Runner unter Port 8080 einen Endpunkt /healthz bereit sowie Kennzahlen im Prometheus-Format.

Sicherheit: Worauf du unbedingt achten solltest

Ein Self-Hosted Runner führt Code aus, den ein Modell erzeugt hat – im Auftrag jeder Person in deiner Organisation. Es gibt keine Zugriffssteuerung pro Umgebung: Wer in der Organisation ist, kann eine Session in jede Umgebung schicken. Behandle jeden Runner-Host entsprechend.

Die wichtigsten Punkte vor dem Anschluss an echte Systeme:

• Ein Container pro Session. Mit --capacity 1 und einem Container, der nach getaner Arbeit verschwindet, teilt sich keine Session ein Dateisystem mit einer anderen.
• Keine breiten Zugangsdaten im Abbild. Kein dauerhafter SSH-Schlüssel, keine Zugriffstoken mit weitem Geltungsbereich. Kurzlebige Zugangsdaten je Session sind der bessere Weg. Für das erstmalige Auschecken gibt es zusätzlich den Git-Proxy von Anthropic, mit dem dein Abbild gar keine Git-Zugangsdaten braucht.
• Ausgehenden Verkehr grundsätzlich sperren. Erlaube nur, was gebraucht wird: api.anthropic.com, deinen Git-Host und die internen Dienste, die die Sessions wirklich erreichen müssen. Das Produkt kann das nicht für dich erzwingen – das gehört an deine Netzwerkgrenze.
• Metadaten-Endpunkt blockieren. Sessions dürfen nicht an die Identität der Maschine kommen. Der Zugriff auf 169.254.169.254 gehört im Container gesperrt.
• Der Umgebungsschlüssel ist heikel. Auf einem festen Verbund liegt er auf jedem Runner-Host – und dort kann ihn jede Session lesen. Wer das vermeiden will, nutzt bedarfsgesteuerte Runner: Dann bleibt der Schlüssel auf einer Maschine, auf der kein fremder Code läuft.

Grenzen der öffentlichen Beta

Was der Runner heute noch nicht kann, ist genauso wichtig wie das, was er kann:

• Kein Zero Data Retention. Organisationen mit aktiviertem Zero Data Retention können die Funktion nicht nutzen.
• Modellabfragen nur über die Anthropic-API. Ein Umweg über Amazon Bedrock, Google Cloud, Microsoft Foundry oder ein eigenes Gateway ist nicht möglich.
• Nicht alle Oberflächen. Sessions aus Claude Tag, Claude Security und Code Review landen bislang nicht auf eigenen Umgebungen.
• Verbindungen laufen außen herum. Angebundene Dienste wie GitHub, Slack oder Linear werden von Anthropic aus aufgerufen, nicht aus deinem Netzwerk heraus. Wenn dieser Verkehr intern bleiben soll, betreibst du entsprechende MCP-Server direkt im Runner-Abbild.
• Nicht gesicherte Arbeit kann verloren gehen. Wird eine Session freigegeben und später fortgesetzt, startet sie auf einem frischen Runner mit einem neuen Klon. Was nicht gesichert wurde, ist weg.
• Repositories nur zu Beginn. Ein Repository, das erst während einer laufenden Session dazukommt, wird nicht ausgecheckt. Wähle gleich am Anfang alles aus, was gebraucht wird.

Anthropic entwickelt hier schnell weiter: Seit dem Erstrelease sind unter anderem Optionen für Proxy-Anmeldung, ein aufgeschobenes Herunterfahren und ein deutlich schnellerer Sessionstart dazugekommen. Ein Blick in die Release-Notes lohnt sich vor jedem Update.

Wie viele Runner brauchst du?

Diese Regel wird gerne übersehen und entscheidet über deine Serverplanung: Ein Runner bindet sich an genau ein Benutzerkonto. Die erste Session, die er annimmt, legt fest, für wen er ab diesem Zeitpunkt arbeitet. Das verhindert, dass sich ausgecheckter Code verschiedener Personen auf einer Festplatte vermischt.

Die Folge: Die kleinste sinnvolle Anzahl an Runnern entspricht der Anzahl an Personen, die gleichzeitig arbeiten sollen. --capacity regelt nur, wie viele Sessions einer Person parallel laufen dürfen – nicht, wie viele Personen bedient werden.

Bleiben Sessions in der Warteschlange hängen, ist das meist der Grund: Alle Runner sind bereits an andere Konten gebunden. Welcher Host an welchem Konto hängt, verrät das Protokoll oder die Kennzahl claude_code_self_hosted_runner_locked_account.

Welcher Server passt für einen Claude-Code-Runner?

Exotische Ausstattung braucht es nicht. Ein Linux-Server mit Root-Zugriff und ausgehendem Internetzugang genügt – also genau das, was ein VPS bietet. Praktisch relevant sind drei Dinge: genügend Arbeitsspeicher und Prozessorleistung für deine Build-Werkzeuge, ausreichend Speicherplatz für die Repository-Kopien und die Möglichkeit, mehrere Runner parallel zu betreiben.

Mit einem Linux VPS von easyname bekommst du genau diese Basis: volle Root-Rechte, freie Softwarewahl, garantierte Ressourcen und ein Rechenzentrum in Wien, das nach ISO/IEC 27001 zertifiziert ist. Docker läuft darauf ohnehin – und damit auch dein Runner-Abbild. Wächst dein Team, buchst du weitere Ressourcen dazu, statt die Einrichtung neu aufzusetzen.

Wenn du dir zuerst ansehen möchtest, wie Container auf einem eigenen Server grundsätzlich funktionieren, ist unser Beitrag zu Docker der passende Einstieg.

Häufige Fragen zu Claude Code am eigenen Server

Läuft das KI-Modell dann auch auf meinem Server?

Nein. Auf deinem Server läuft die Ausführung: Dateien, Befehle, Repositories. Die Modellabfragen gehen weiterhin verschlüsselt an die Anthropic-API. Einen eigenen Server zu nutzen bedeutet nicht, das Modell selbst zu betreiben.

Brauche ich einen bestimmten Tarif?

Ja. Selbst gehostete Umgebungen stehen als öffentliche Beta für Team- und Enterprise-Organisationen zur Verfügung und sind standardmäßig deaktiviert. Eine Person mit Inhaber- oder Administratorrolle muss sie freischalten.

Funktioniert der Runner unter Windows?

Nicht direkt. Als Host werden Linux und macOS unterstützt. Auf Windows-Maschinen betreibst du den Runner in einem Linux-Container. Für die Personen im Team ändert das nichts – sie starten ihre Sessions ohnehin im Browser.

Was passiert, wenn mein Server neu startet?

Die Session wandert zurück in die Warteschlange und wird von einem anderen Runner übernommen. Beim Fortsetzen wird das Repository neu geklont – nicht gesicherte Änderungen sind dann verloren. Deshalb gehört ein Werkzeug davor, das den Runner nach dem Beenden zuverlässig neu startet, und genügend Zeit zum geordneten Aufräumen.

Kostet der Betrieb am eigenen Server zusätzlich?

Sessions in einer selbst gehosteten Umgebung verbrauchen dasselbe Nutzungskontingent deiner Organisation wie Sessions bei Anthropic. Dazu kommen deine Serverkosten.

Wie finde ich heraus, warum eine Session nicht startet?

Der eingebaute Diagnosebefehl liest Protokolle und Zustand des Runners aus:

claude self-hosted-runner doctor

Die häufigsten Ursachen sind fehlende Git-Zugangsdaten im Abbild, nicht installierte Build-Werkzeuge und ein Arbeitsverzeichnis, in das der Runner nicht schreiben darf.

Fazit

Claude Code am eigenen Server ist kein Schalter, sondern eine Infrastrukturentscheidung. Wer sie trifft, bekommt dafür etwas, das vorher nicht möglich war: KI-gestützte Entwicklungsarbeit, die im eigenen Netzwerk stattfindet und interne Systeme erreicht, ohne sie nach außen zu öffnen. Für Teams mit Vorgaben zur Datenhaltung ist das der Unterschied zwischen „geht nicht” und „geht”.

Die technische Grundlage dafür ist überschaubar: ein Linux-Server mit Root-Zugriff, ausgehendem Internetzugang und genug Reserven für deine Werkzeuge. Wenn du deinen Runner in Österreich betreiben möchtest, findest du bei unseren Linux VPS die passende Basis – mit Rechenzentrum in Wien und deutschsprachiger Unterstützung, wenn es einmal hakt.