SSD Nodes Learn Hosting plans →
Anleitungen Matt ConnorVon Matt Connor

HarnessRouter selbst hosten: Eine API für Agenten

Betreiben Sie Codex, Claude Code und Hermes über eine selbst gehostete API. Mit Docker-Befehl, Loopback-Bindung, zu änderndem Erstpasswort und TLS-Zugriff.

Was HarnessRouter entfernt

Sie hosten HarnessRouter Community Edition selbst, um mehrere Agent-Harnesses auf einem Server, den Sie verwalten, über eine gemeinsame API anzusprechen. Ein Agent-Harness ist ein Befehlszeilenprogramm, das ein Modell in einer Schleife steuert: Es verwaltet eine Sitzung, bearbeitet Dateien, führt Befehle aus und streamt den Fortschritt zurück an den Anforderer. Codex, Claude Code und Hermes übernehmen diese Aufgabe jeweils selbst und bringen jeweils eine eigene Installation, ein eigenes Format für Zugangsdaten und ein eigenes Sitzungsmodell mit. HarnessRouter führt sie alle in einem Container aus und stellt ihnen einen gemeinsamen HTTP-Endpunkt, eine gemeinsame Anmeldung und einen gemeinsamen Secret Store voran.

Das ist die gesamte Idee. Die Kosten sollten Sie jedoch ausdrücklich berücksichtigen. Sie fügen Ihrem Server einen Container, eine Anmeldung, ein Volume und einen Upgrade-Pfad hinzu, damit aus mehreren Komponenten eine einzige wird. Wenn Sie heute genau ein Harness ausführen, ist diese Einrichtung schlechter, als das Harness direkt zu installieren. Dieser Kompromiss wird im letzten Abschnitt behandelt. Lesen Sie ihn daher, bevor Sie die Bereitstellung durchführen.

Alle folgenden Angaben wurden mit dem Image-Tag 0.5.5 geprüft, das am 19. August 2026 abgerufen wurde. Das Projekt veröffentlicht an den meisten Tagen neue Tags. Prüfen Sie daher den tatsächlich verwendeten Tag, statt sich in einem Monat auf diese Seite zu verlassen. Am 8. November 2026 wurde diese Seite anhand der aktuellen Dokumentation und des Quellcodes des Projekts erneut geprüft. Dabei zeigte latest auf 0.38.5. Stellen, an denen sich aktuelle Releases anders verhalten, sind entsprechend gekennzeichnet. Die Befehle stammen aus dem Projekt-Repository unter github.com/HarnessRouter/harnessrouter. Sie standen in der README unter 0.5.5. Die Details zur Einrichtung befinden sich inzwischen unter docs/self-hosting-guide.md im selben Repository.

Was das Unified Harness Protocol tatsächlich ist

HarnessRouter implementiert das Unified Harness Protocol (UHP), das unter unifiedharnessprotocol.org veröffentlicht wird. UHP beschreibt, wie ein Produkt eine Aufgabe auf einem Harness startet, die laufende Aufgabe verfolgt, Sitzungen und Dateien verwaltet und Fehler meldet. Die Spezifikation wird nach Datum versioniert. Die am 19. August 2026 aktuelle Version trug das Datum 2026-08-11. Am 8. November 2026 führt die Website 2026-10-19 als aktuelle Version auf. Sie bezeichnet das Protokoll weiterhin als Entwurfsstandard, der „stabil genug für darauf aufbauende Implementierungen und so versioniert ist, dass er sicher geändert werden kann“.

Lesen Sie die Bezeichnung „offener Standard“ hier genau. Dasselbe Unternehmen erstellt die Spezifikation, die Referenzimplementierung und die Conformance-Suite, die entscheidet, wer konform ist. Die Governance-Regeln des Projekts legen außerdem fest, dass keine Änderung übernommen wird, wenn nicht alle drei Komponenten gemeinsam aktualisiert werden. Am 9. November 2026 beschreibt die Protokoll-Homepage diese Suite als 110 ausführbare Prüfungen. Die Conformance-Seite nennt dagegen 101. Der im Self-Hosting-Leitfaden aufgezeichnete Referenzlauf vom 4. September 2026 bestand 64 Prüfungen. Die veröffentlichten Zahlen stimmen daher nicht überein. Das Changelog des Projekts datiert die sechs zusätzlichen Prüfungen für Verzweigungen auf den 4. November 2026. Das ist bei einem so jungen Protokoll üblich. Die Apache-2.0-Lizenz bedeutet, dass Sie jeden Teil davon forken können. Sie bedeutet jedoch auch, dass UHP noch kein Standard mehrerer Anbieter ist. Betrachten Sie UHP als aufkommendes Protokoll: nützlich, in Bewegung und so konzipiert, dass Ihr eigener Code es ohne vollständige Neuentwicklung nicht mehr verwenden können muss.

Voraussetzungen

Sie benötigen Docker und ungefähr 4 GB freien Speicherplatz. Außerdem brauchen Sie einen API-Schlüssel eines Model-Providers, für den Sie bereits bezahlen. Der Image-Pull umfasst etwa 700 MB. Der restliche Speicherplatz wird von den Agent-CLIs und den Workspaces belegt, in denen sie Dateien erstellen. Das Image enthält kein gebündeltes Modell und keinen Testschlüssel. Aufgaben schlagen daher fehl, bis Sie einen Provider verbinden. HarnessRouter steht unter der Apache-2.0-Lizenz. Für die Agent-CLIs gelten weiterhin deren eigene Lizenzen und Nutzungsbedingungen. Die Lizenz des Repositorys ersetzt diese nicht. Die Agent-CLIs werden beim ersten Start abgerufen und nicht im Image ausgeliefert.

HarnessRouter mit einem einzigen docker run selbst hosten

docker pull harnessrouter/harnessrouter
docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  harnessrouter/harnessrouter

Beobachten Sie anschließend, wie der Container gestartet wird. Der erste Start dauert länger. Die Logs zeigen den Grund.

docker logs -f harnessrouter

Während des Starts sehen Sie Zeilen wie diese:

installing Claude Code (Anthropic's terms apply)…
installing Codex (Apache-2.0)…
installing Hermes (check its upstream license before use)…

Warten Sie auf ready on :3000. Die aktuelle Anleitung misst ungefähr eine halbe Minute ab dem Zeitpunkt, an dem docker run Ihre Eingabeaufforderung zurückgibt, nicht ab dieser Zeile. Falls http://localhost:3000 unmittelbar nach der Bereitschaftsmeldung nicht antwortet, versuchen Sie es nach einigen Sekunden erneut. Installierte CLIs werden auf dem Volume zwischengespeichert. Spätere Starts sind daher normalerweise deutlich schneller. Ein später hinzugefügtes Backend oder ein Backend, dessen Installation zuvor fehlgeschlagen ist, kann jedoch weiterhin eine Installation auslösen.

Aus diesem Download ergeben sich zwei wichtige Punkte, die auf einem VPS relevant sind. Erstens benötigt der erste Start ausgehenden Netzwerkzugriff. Das Image ist nicht vollständig autark. Ein System hinter einer Egress-Filterung oder ohne ausgehende Route kann die Agent-CLIs daher nicht herunterladen. Sowohl 0.5.5 als auch aktuelle Releases behandeln fehlgeschlagene Installationen als nicht kritisch und nennen sie im Log. Prüfen Sie daher, welche Backends in der backends available:-Zeile fehlen. Zweitens installieren Sie Software von Drittanbietern unter deren jeweiligen Nutzungsbedingungen. Claude Code wird unter den Bedingungen von Anthropic bereitgestellt, Hermes unter den Bedingungen seines Upstream-Projekts. Prüfen Sie daher beide, bevor Sie die Software kommerziell einsetzen.

-v harnessrouter:/data erstellt ein benanntes Docker-Volume. Alle dauerhaft gespeicherten Daten liegen in /data: die SQLite-Datenbanken, die gespeicherten Dateien, der Secret Store und die Agent-Arbeitsbereiche. Wenn Sie dieses Volume löschen, löschen Sie die gesamte Instanz, einschließlich der Provider-Keys und aller Transkripte. Erstellen Sie das Backup bei gestopptem Container. Das Kopieren einer SQLite-Datenbank während eines Schreibvorgangs kann eine Datei erzeugen, die sich anschließend nicht öffnen lässt. Dieselbe Reihenfolge aus Stoppen und anschließendem Kopieren gilt für jeden zustandsbehafteten Container auf dem System. Die Details unterscheiden sich jedoch je nach Dienst, da PhotoPrism und Immich jeweils eigene Backup-Befehle benötigen.

docker stop harnessrouter
docker run --rm -v harnessrouter:/data -v "$PWD":/backup alpine \
  tar czf /backup/harnessrouter-data.tgz -C / data
docker start harnessrouter

Die Compose-Variante und die Zeile, die Sie ändern müssen

Das Repository enthält eine Compose-Datei. Sie veröffentlicht jetzt "127.0.0.1:3000:3000" und bindet den Host-Port an das Loopback-Interface. Die Datei 0.5.5 veröffentlichte "3000:3000". Ändern Sie diese Zeile, wenn Sie die ältere Datei auf einem öffentlichen Server verwenden.

services:
  harnessrouter:
    image: harnessrouter/harnessrouter:0.5.5
    ports:
      - "127.0.0.1:3000:3000"
    env_file:
      - .env
    volumes:
      - harnessrouter-data:/data
    restart: unless-stopped

volumes:
  harnessrouter-data:

Ein Unterschied zum aktuellen Upstream ist das fest gesetzte Versions-Tag anstelle von latest. Das Festlegen einer Version ist wichtig, weil sich Releases schnell ändern: Docker Hub führte bei einer Prüfung am 8. November 2026 sowohl 0.38.4 als auch 0.38.5 als innerhalb des vergangenen Tages veröffentlicht. Eine Agent-Laufzeit, die sich während des Betriebs ändert, ist schwer zu debuggen. Legen Sie das aktuelle Release fest, statt 0.5.5 von dieser Seite zu übernehmen. Am 9. November 2026 war das 0.40.0. Kopieren Sie anschließend die Umgebungsdatei, schützen Sie ihre Berechtigungen und starten Sie den Dienst.

cp .env.example .env
chmod 600 .env
docker compose up -d
docker compose logs -f

.env enthält Ihren Provider-Schlüssel im Klartext. Daher ist der Modus 600 das Minimum. Falls Ihnen das Unterkommando docker compose nicht vertraut ist, behandelt das Spickzettel für Docker-Compose-Befehle die täglichen Befehle.

Warum der Port auf 127.0.0.1 und nicht auf 0.0.0.0 veröffentlicht wird

-p 3000:3000 veröffentlicht den Port standardmäßig auf jeder Schnittstelle des Hosts. -p 127.0.0.1:3000:3000 veröffentlicht den Host-Port auf dem Loopback-Interface. Docker-Versionen vor 28.0.0 erlauben es Hosts im selben L2-Segment, auf über localhost veröffentlichte Ports zuzugreifen. Explizit aktiviertes Direct Routing kann den Container-Port trotz einer Loopback-Zuordnung des Hosts ebenfalls zugänglich machen. Der Container lauscht standardmäßig intern auf Port 3000. Über PORT lässt sich dieser Port konfigurieren. Ändern Sie daher die linke Portnummer, um einen Konflikt mit einem bereits belegten Host-Port zu vermeiden. Prüfen Sie die Ausgabe:

docker port harnessrouter
sudo ss -ltnp | grep 3000

ss mit 127.0.0.1:3000 auszugeben, ist korrekt. 0.0.0.0:3000 bedeutet, dass die Konsole an allen IPv4-Schnittstellen gebunden ist. Der Zugriff aus dem öffentlichen Internet hängt weiterhin vom Routing und von den Filterregeln ab. In diesem Fall ist das problematischer als bei den meisten Self-Hosting-Anwendungen, weil die Konsole Harnesses erstellt, jedes Transkript liest, Agents ausführt und diesen Agents eine Shell sowie ein echtes Dateisystem in ihrem Arbeitsbereich bereitstellt. Außerdem enthält sie den von Ihnen verbundenen Provider-Key. Jeder, der eine ungeschützte Konsole erreicht, kann Ihre Arbeit lesen, Befehle ausführen und Ihren Key verwenden.

Eine ufw-Deny-Regel schützt Sie davor nicht. Docker leitet veröffentlichten Container-Verkehr über eigene Regeln um, bevor er die von ufw verwalteten Chains erreicht. Daher belegt die Anzeige eines Ports als verweigert in sudo ufw status nicht, dass der veröffentlichte Port tatsächlich blockiert ist. Testen Sie von einem anderen Rechner und nicht vom VPS aus. Andernfalls testen Sie nichts. Das ist dieselbe Lehre wie bei dsh headless auf Port 3080 ausführen: Binden Sie den Dienst an das Loopback-Interface und legen Sie anschließend bewusst fest, wie Sie darauf zugreifen.

Ändern Sie das Standardpasswort vor allen anderen Schritten

Melden Sie sich unter http://localhost:3000 mit dem Benutzernamen harnessrouter und dem von Ihrer Instanz erzeugten initialen Passwort an. Lesen Sie es mit folgendem Befehl aus:

docker exec harnessrouter cat /data/selfhost-initial-password

Das veröffentlichte gemeinsame Passwort harnessrouter funktionierte in 0.5.5. Aktuelle Installationen akzeptieren dieses Standardpasswort nicht mehr.

Ändern Sie es auf der Seite Profile oder legen Sie es beim Start für eine skriptgesteuerte Bereitstellung fest. HR_AUTH_USER und HR_AUTH_PASSWORD geben die initialen Zugangsdaten vor. Zugangsdaten, die unter Profile gespeichert wurden, haben Vorrang.

docker run -d --name harnessrouter \
  -p 127.0.0.1:3000:3000 \
  -v harnessrouter:/data \
  -e HR_AUTH_USER='you' \
  -e HR_AUTH_PASSWORD='the-password-you-chose' \
  harnessrouter/harnessrouter

Für die lokale Console-Anmeldung gibt es keine E-Mail zum Zurücksetzen des Passworts. Wenn Sie das Passwort verlieren, löschen Sie die Authentifizierungsdatei im Volume und starten Sie die Anwendung neu. Melden Sie sich anschließend mit den von Ihnen konfigurierten Werten HR_AUTH_USER und HR_AUTH_PASSWORD oder mit dem erzeugten initialen Passwort an, falls Sie keine eigenen Werte angegeben haben.

docker stop harnessrouter
docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json
docker start harnessrouter

HR_AUTH_DISABLED=1 entfernt die Anmeldesperre vollständig. Die Self-Hosting-Anleitung bezeichnet das als „nur auf einem Rechner sinnvoll, den niemand sonst erreichen kann“. Ein VPS mit einer öffentlichen IP-Adresse ist kein solcher Rechner. Lassen Sie die Anmeldesperre daher aktiviert, außer Sie führen die Anwendung auf einem Laptop aus.

Prüfen Sie Ihre Version, denn den alten Versionen fehlt jede Zugriffssperre

Nehmen Sie diesen Teil ernst. Die Versionen 0.1.x und 0.2.0 wurden vollständig ohne Authentifizierungssperre veröffentlicht: Wer Port 3000 erreichen konnte, war bereits in der Konsole. 0.3.0 war die erste Version mit Anmeldung. Diese Seite verzeichnete diese älteren Tags zuletzt am 12. Oktober 2026 als veröffentlicht und abrufbar; ihre aktuelle Verfügbarkeit wurde am 8. November 2026 nicht bestätigt.

Am 19. August 2026 war 0.5.5 der neueste veröffentlichte Tag und auf den 18. August 2026 datiert. Am 8. November 2026 verwies latest auf 0.38.5. Prüfen Sie, welche Version Sie verwenden, und vergleichen Sie sie anschließend mit der Tag-Liste auf Docker Hub:

docker image ls harnessrouter/harnessrouter

Alles unter 0.3.0 sollte jetzt ersetzt werden und nicht erst eingeplant werden. Bei älteren Releases mit dem gemeinsamen Standardpasswort muss dieses weiterhin geändert werden. Aktuelle Installationen erzeugen ein initiales Passwort und fordern Sie auf, ein eigenes zu wählen. Betrachten Sie die Versionsnummern auf dieser Seite nicht als aktuell. Sie waren an den angegebenen Tagen korrekt, und dieses Projekt veröffentlicht schnell neue Versionen.

Einen Provider verbinden

Es läuft nichts, bevor kein Model-Provider verbunden ist. Fügen Sie einen Provider über Bring your own key im Kontomenü hinzu oder übergeben Sie ihn in der Umgebung an docker run. Der Wert ist JSON. Setzen Sie ihn daher in der Shell in Anführungszeichen:

-e HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC='{"name":"anthropic","provider":"anthropic","api_key":"sk-ant-…"}'

.env.example benennt pro Provider-Familie eine Verbindungsvariable: HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC für das claude-code-Backend, HR_SECRET_GLOBAL_HARNESS_CONN_OPENAI für das codex-Backend, HR_SECRET_GLOBAL_HARNESS_CONN_GOOGLE für das gemini-Backend und HR_SECRET_GLOBAL_HARNESS_CONN_CUSTOM für jeden OpenAI-kompatiblen Endpunkt. Dort können Sie einen Aggregator oder Ihren eigenen Inferenzserver eintragen. Mit den zugehörigen Variablen HR_SECRET_GLOBAL_HARNESS_POLICY_CLAUDE, HR_SECRET_GLOBAL_HARNESS_POLICY_CODEX und HR_SECRET_GLOBAL_HARNESS_POLICY_HERMES legen Sie fest, welche Verbindung das jeweilige Backend standardmäßig verwendet. Außerdem gibt es pro Backend eine Policy-Variable. HR_SECRET_KEY ist davon unabhängig. Aktuelle Releases verschlüsseln darunter gespeicherte Zugangsdaten und erzeugen einen Schlüssel in /data/secret-key, wenn Sie keinen angeben. Verwenden Sie denselben Schlüssel bei Neustarts und Upgrades. Wenn Sie ihn bei einer bestehenden Instanz getrennt von den Daten aufbewahren möchten, setzen Sie HR_SECRET_KEY auf den Wert aus dieser Datei und löschen Sie die Datei.

HR_BACKENDS legt fest, welche Backends installiert und geladen werden, wie in HR_BACKENDS=claude,codex,hermes. Wenn die Variable nicht gesetzt ist, installieren aktuelle Releases standardmäßig eine deutlich längere Liste mit 30 Backends, darunter claude, codex und hermes sowie opencode, gemini, goose und weitere. Eine gekürzte Liste spart daher Speicherplatz und Zeit beim ersten Start. In der aktuellen Self-Hosting-Anleitung heißt es: „Lassen Sie alle Backends aus HR_BACKENDS weg, die Sie nicht verwenden werden.“ Das dortige schlanke Beispiel ist HR_BACKENDS=opencode und lässt Hermes vollständig weg. Wenn die Installation eines Backends fehlschlägt, ist das kein fataler Fehler. Die übrigen Backends funktionieren weiterhin. Eine Aufgabe für ein nicht installiertes Backend wird mit „not installed“ abgelehnt, während das Log des Containers die fehlgeschlagene Installation nennt. Die README von 0.5.5 enthielt ein bekanntes Problem: Wenn hermes weggelassen wurde, beendete sich der Container sofort mit Status 1 und ohne Fehlermeldung. Der Entry Point dieses Tags behebt den Fehler jedoch bereits. Die Kommentare beschreiben dort die frühere Implementierung. Wenn Hermes das einzige gewünschte Harness ist, ist das Ausführen des Hermes-Agenten auf einer eigenen VPS die kleinere Bereitstellung.

API ohne die Konsole aufrufen

Die Konsole ist optional. Beide Varianten verwenden dieselbe API mit einem Responses-ähnlichen Vertrag. Melden Sie sich zuerst an, um ein Session-Cookie zu erhalten:

curl -c hr.cookies http://localhost:3000/api/selfhost/login \
  -H 'content-type: application/json' \
  -d '{"username":"harnessrouter","password":"your-password"}'

Senden Sie anschließend eine Aufgabe. Geben Sie dabei in metadata.harness_id den Harness und ein Modell an, das Ihr verbundener Provider tatsächlich bereitstellt:

curl -s -b hr.cookies http://localhost:3000/api/harness/v1/responses \
  -H 'content-type: application/json' \
  -d '{"input":"Reply with exactly this and nothing else: it works.",
       "metadata":{"harness_id":"codex"},
       "model":"gpt-5.4-mini",
       "stream":false}'

Ein JSON-Objekt mit einem Ausgabeblock und einer Tokenanzahl bedeutet, dass der Harness ausgeführt wurde. Wenn Sie harness_id von codex in claude-code ändern, wird dieselbe Anfrage an einen anderen Harness gesendet. Genau dieser Wechsel ist der eigentliche Zweck dieser Software. Beachten Sie, dass die ID claude-code lautet, obwohl der Backend-Name HR_BACKENDS und die Policy-Variable claude ist. Mit der oben beschriebenen benutzerdefinierten Verbindung können Sie einen Harness auf einen bereits von Ihnen betriebenen OpenAI-kompatiblen Endpunkt verweisen. So ist beispielsweise ein selbst gehosteter DeepSeek-Harness auf einem VPS angebunden.

Der Ablauf mit Session-Cookie wird für das lokale Debugging weiterhin unterstützt. Für ein Produkt-Backend empfiehlt die aktuelle Dokumentation, unter API Keys einen HarnessRouter API key zu erstellen und ihn als Bearer-Token zu senden, anstatt eine Console-Sitzung zu verwalten.

Greifen Sie vom Laptop darauf zu, ohne einen Port zu veröffentlichen

Dafür gibt es zwei Möglichkeiten. Keine davon veröffentlicht einen direkten Port auf 0.0.0.0.

Ein SSH-Tunnel ist die einfachste Lösung. Auf dem Server muss nichts installiert werden. Er leitet einen lokalen Port auf Ihrem Rechner an die Loopback-Adresse der VPS weiter.

ssh -N -L 3000:127.0.0.1:3000 you@your-vps

Lassen Sie den Tunnel laufen und öffnen Sie http://localhost:3000 im Browser. Wenn SSH bind: Address already in use ausgibt, verwendet bereits ein anderer Prozess auf Ihrem Laptop den Port 3000. Wählen Sie dann mit -L 3100:127.0.0.1:3000 einen anderen lokalen Port und öffnen Sie Port 3100 im Browser.

Ein Reverse Proxy mit TLS-Terminierung ist die richtige Lösung, wenn andere Personen Zugriff benötigen. Der Proxy verwaltet das TLS-Zertifikat und leitet Anfragen an die Loopback-Adresse weiter. Der Self-Hosting-Leitfaden enthält eine Caddy-Konfiguration:

console.example.com {
    encode zstd gzip
    reverse_proxy 127.0.0.1:3000 {
        flush_interval -1      # agent turns stream for minutes; never buffer them
    }
}

flush_interval -1 deaktiviert ausdrücklich das Response-Buffering von Caddy. Caddy überträgt text/event-stream-Antworten auch ohne diese Einstellung sofort. Agent erzeugt über mehrere Minuten hinweg Stream-Tokens. Ein Proxy, der die Antwort puffert, hält diese Tokens bis zum Ende des Vorgangs zurück. Dadurch wirkt die Konsole eingefroren und gibt anschließend alles auf einmal aus. Das entsprechende Nginx-Äquivalent innerhalb des location-Blocks ist proxy_buffering off;. Unabhängig von Ihrer Wahl muss der DNS-Name auf den Proxy und der Container auf die Loopback-Adresse zeigen. Nginx, Caddy und Traefik als Reverse Proxy vergleichen erläutert, welcher Proxy zu Ihrem System passt.

Führen Sie es unter einem eigenen Benutzer aus, nicht als root

Der Docker-Daemon läuft als root. Die Mitgliedschaft in der Gruppe docker entspricht daher root-Rechten, weil ein Mitglied einen Container starten kann, der das Host-Dateisystem einbindet. Wenn Sie also „das Team der Docker-Gruppe hinzufügen“, vergeben Sie root-Rechte auf dem Server, auf dem Ihr Provider-Schlüssel liegt.

Die einfache Variante: Erstellen Sie ein Dienstkonto, dem die Compose-Datei und .env gehören. Halten Sie diese Dateien aus gemeinsam genutzten Home-Verzeichnissen heraus.

sudo adduser --disabled-password --gecos "" harness
sudo install -d -o harness -g harness -m 750 /srv/harnessrouter

Versuchen Sie nicht, dieses Ziel zu erreichen, indem Sie --user zu docker run oder user: zur Compose-Datei hinzufügen. Die aktuelle Anleitung schreibt vor, dass der Container als root gestartet werden muss. Ab 0.8.2 verweigert er den Start auf jede andere Weise. Im Log steht dazu eine entsprechende Zeile.

Die robustere Variante ist Rootless Docker. Dabei läuft auch der Daemon selbst unter diesem nicht privilegierten Benutzer. Für newuidmap und newgidmap wird das Paket uidmap benötigt. Außerdem benötigt der Benutzer mindestens 65536 untergeordnete UIDs in /etc/subuid und /etc/subgid. uidmap ist im Ubuntu-Archiv enthalten, docker-ce-rootless-extras jedoch nicht. Dieses Paket wird aus dem Docker-eigenen apt-Repository unter download.docker.com bereitgestellt, das bei der Installation der Docker Engine hinzugefügt wird. Wenn Sie die Engine nicht aus diesem Repository installiert haben, gibt grep -rl download.docker.com /etc/apt/sources.list.d/ nichts aus. Die folgende Installation findet das Paket dann nicht.

sudo apt install -y uidmap docker-ce-rootless-extras
sudo loginctl enable-linger harness
sudo -iu harness
dockerd-rootless-setuptool.sh install
export DOCKER_HOST=unix:///run/user/$(id -u)/docker.sock
systemctl --user enable --now docker

loginctl enable-linger hält die systemd-Instanz des Benutzers nach der Abmeldung aktiv und startet sie beim Booten. Prüfen Sie das Ergebnis mit docker info. Der Befehl listet rootless unter „Security Options“ auf. Rootless mode kann ohne zusätzliche Konfiguration keine Ports unter 1024 binden. Das ist hier unproblematisch, weil Port 3000 darüber liegt. Die Einrichtung des Kontos selbst wird unter Benutzer mit geringstmöglichen Rechten auf einem VPS erstellen beschrieben.

Was fehlschlägt und was Sie sehen

Der Container wird eine Sekunde nach dem Start beendet, und die Logs sind leer. docker ps -a zeigt Exited (1). Ein früherer Entrypoint schlug fehl, wenn HR_BACKENDS hermes nicht enthielt. 0.5.5 enthält die Korrektur bereits, obwohl die README das Problem weiterhin aufführt. Diagnostizieren Sie diesen Fehler nicht allein anhand des Exit-Status. Lesen Sie bei einem aktuellen Tag die letzte Zeile von docker logs: Ab 0.8.2 wird ein mit --user gestarteter Container mit einer Zeile beendet, die besagt, dass er als root starten muss.

Der erste Start wird nie beendet. Das Log endet nach einer installing-Zeile, und ready on :3000 erscheint nie. Prüfen Sie, ob der Server das Netzwerk erreichen kann, um die Agent-CLIs abzurufen, da diese nicht im Image enthalten sind. Sowohl 0.5.5 als auch aktuelle Releases tolerieren abgeschlossene Installationsfehler. Sie nennen fehlgeschlagene Installationen im Log und lassen sie aus der backends available:-Zeile weg. Korrigieren Sie die ausgehende Route oder die Proxy-Einstellungen und starten Sie den Container anschließend neu.

Die Konsole wird geladen, und jede Aufgabe schlägt fehl. Es ist kein Provider verbunden. Das Image enthält weder ein gebündeltes Modell noch ein kostenloses Kontingent. Eine neue Instanz kann daher die Anmeldung ermöglichen und trotzdem keine Aufgabe ausführen.

Die Konsole bleibt hinter einem Proxy mitten in der Antwort hängen. Die Ausgabe erscheint erst in einem Block, wenn der Durchlauf beendet ist. Ursache ist die Antwortpufferung. Setzen Sie in Caddy flush_interval -1 oder in Nginx proxy_buffering off;.

Sie können die Anwendung von Ihrem Laptop aus nicht erreichen, obwohl der Tunnel aktiv ist. Führen Sie auf dem Server docker port harnessrouter aus. Wenn keine Ausgabe erscheint, veröffentlicht der Container keine Ports. Prüfen Sie daher das Port-Mapping und den Netzwerkmodus.

Ist der Betrieb sinnvoll?

Der Betrieb lohnt sich, wenn Sie tatsächlich mehr als ein Harness verwenden und statt jeweils drei Endpunkten und drei Credential-Speichern nur einen Endpunkt und einen Credential-Speicher benötigen. Er lohnt sich auch, wenn Sie ein Produkt darauf aufbauen und das Harness als Konfigurationswert statt als Anlass für eine erneute Implementierung verwenden möchten. Das ermöglicht UHP, wobei der oben genannte Hinweis zum geringen Alter des Protokolls gilt.

Der Betrieb lohnt sich nicht, wenn Sie nur ein Harness verwenden. Die Installation dieser CLI auf dem Server umfasst weniger Komponenten, und zwischen Ihnen und der CLI befindet sich keine Anmeldung. Der Ansatz passt außerdem nicht, wenn mehrere Agents gemeinsam eine Aufgabe bearbeiten sollen, statt dass eine API vor mehreren Harnesses liegt. Dafür benötigen Sie ein anderes Tool: Siehe ein Multi-Agent-Harness wie Omnigent für dieses Muster. Die Bereitstellungsregeln ändern sich in beiden Fällen nicht. Binden Sie an Loopback, ändern Sie das Passwort, verwenden Sie ein festgelegtes aktuelles Release und einen eigenen Benutzer.

FAQ

Ist es sicher, HarnessRouter auf Port 3000 zu veröffentlichen?

Nein. Die Konsole erstellt Harnesses, liest jedes Transkript, führt Agents mit Shell- und Dateisystemzugriff aus und enthält den von Ihnen hinterlegten Provider-Schlüssel. Eine ungeschützte Konsole gibt daher all diese Funktionen und Daten preis. Veröffentlichen Sie den Dienst auf dem Loopback-Interface mit -p 127.0.0.1:3000:3000 und greifen Sie über einen SSH-Tunnel oder einen Reverse Proxy mit TLS-Terminierung darauf zu. Eine ufw-Deny-Regel reicht allein nicht aus: Docker leitet veröffentlichten Containerverkehr um, bevor er die von ufw verwalteten Chains erreicht. Prüfen Sie dies mit sudo ss -ltnp | grep 3000. Die Ausgabe sollte 127.0.0.1:3000 lauten. Testen Sie den Zugriff außerdem von einem anderen Rechner aus. Verwenden Sie Docker 28.0.0 oder neuer, um die frühere Freigabe des Localhost-Zugriffs über dasselbe L2-Netz zu vermeiden, und prüfen Sie, dass kein direktes Routing aktiviert wurde.

Welche HarnessRouter-Version hat die Anmeldesperre eingeführt?

0.3.0. Die Versionen 0.1.x und 0.2.0 wurden vollständig ohne Authentifizierung veröffentlicht. Wer diese Versionen einsetzt, verlässt sich daher darauf, dass niemand den Port findet. Auf dieser Seite waren diese Tags zuletzt am 12. Oktober 2026 als veröffentlicht und abrufbar verzeichnet. Ihre aktuelle Verfügbarkeit wurde am 8. November 2026 nicht bestätigt. Am 19. August 2026 war 0.5.5 der neueste Tag, datiert auf den 18. August 2026. Am 8. November 2026 verwies latest auf 0.38.5. Führen Sie docker image ls harnessrouter/harnessrouter aus, um Ihre installierte Version anzuzeigen. Vergleichen Sie sie mit der Tag-Liste auf Docker Hub und nicht mit dieser Seite. Wählen Sie anschließend ein eigenes Passwort. Aktuelle Installationen erzeugen ein initiales Passwort, anstatt das alte gemeinsame Standardpasswort zu akzeptieren.

Warum beendet sich der Container direkt nach dem Setzen von HR_BACKENDS?

Bei einer aktuellen Version sollte das nicht passieren. Die Anleitung zum Self-Hosting empfiehlt, nicht benötigte Backends wegzulassen. Ein Backend, dessen Installation fehlschlägt, ist dabei kein fataler Fehler. Eine frühere Implementierung wurde mit Status 1 und ohne Fehlermeldung beendet, wenn hermes fehlte. Der Quellcode von 0.5.5 behebt diesen Fehler bereits, obwohl die README-Datei ihn weiterhin aufführt. Lesen Sie bei einem aktuellen Tag docker logs: Ab 0.8.2 beendet sich ein mit --user gestarteter Container mit einer Zeile, die besagt, dass er als root gestartet werden muss.

Benötigt HarnessRouter beim ersten Start Internetzugriff?

Ja. Die Agent-CLIs werden beim ersten Start abgerufen, anstatt im Image enthalten zu sein. Für jede CLI gelten weiterhin deren eigene Lizenz und Nutzungsbedingungen. Sowohl 0.5.5 als auch aktuelle Versionen protokollieren fehlgeschlagene Installationen und lassen die anderen Backends starten. Installierte CLIs werden auf dem Volume zwischengespeichert. Spätere Starts sind daher normalerweise schneller. Backend-Tools und die von Ihnen ausgeführten Aufgaben können jedoch weiterhin Netzwerkzugriff benötigen. Auch ein neues oder zuvor fehlgeschlagenes Backend kann eine erneute Installation auslösen.

Ich habe das Passwort der Konsole verloren. Wie erhalte ich wieder Zugriff?

Für die lokale Console-Anmeldung gibt es keine E-Mail zum Zurücksetzen des Passworts. Stoppen Sie den Container, löschen Sie /data/selfhost-auth.json aus dem Volume und starten Sie den Container erneut. Melden Sie sich anschließend mit Ihrem konfigurierten HR_AUTH_USER und HR_AUTH_PASSWORD oder mit dem erzeugten initialen Passwort an, falls Sie kein eigenes Passwort angegeben haben. Legen Sie auf der Profile-Seite ein neues Passwort fest. Wenn der Container und das Volume beide harnessrouter heißen, lautet die Abfolge docker stop harnessrouter, anschließend docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json und danach docker start harnessrouter. Lesen Sie das erzeugte Passwort mit docker exec harnessrouter cat /data/selfhost-initial-password aus.

War dieser Artikel hilfreich?