SSD Nodes Learn Hosting plans →
Przewodniki Matt ConnorAutor: Matt Connor

HarnessRouter: konfiguracja własnego API dla agentów

Instrukcja wdrożenia HarnessRouter w Dockerze dla Codex, Claude Code i Hermes. Opisano konfigurację loopback, zmianę domyślnych poświadczeń oraz poprawne zabezpieczenie TLS.

Co eliminuje HarnessRouter

HarnessRouter Community Edition jest hostowany samodzielnie, aby umieścić jeden interfejs API przed kilkoma agentami typu harness na posiadanym serwerze. Agent harness to program wiersza poleceń, który steruje modelem w pętli: utrzymuje sesję, edytuje pliki, wykonuje polecenia i przesyła postępy do podmiotu zlecającego pracę. Codex, Claude Code oraz Hermes realizują to zadanie, a każdy z nich posiada własną instalację, format poświadczeń oraz definicję sesji. HarnessRouter uruchamia je wszystkie wewnątrz jednego kontenera, udostępniając jeden punkt końcowy HTTP, jeden mechanizm logowania oraz jeden magazyn kluczy.

To cała koncepcja, a koszt tego rozwiązania należy wyraźnie podkreślić. Dodajesz kontener, logowanie, wolumen oraz ścieżkę aktualizacji do swojego serwera, aby połączyć kilka ruchomych elementów w jeden. Jeśli obecnie uruchamiasz dokładnie jeden harness, ta konfiguracja jest mniej wydajna niż bezpośrednia instalacja tego narzędzia. Ten kompromis został omówiony w ostatniej sekcji, dlatego należy się z nim zapoznać przed wdrożeniem.

Wszystkie poniższe informacje zostały zweryfikowane względem tagu obrazu 0.5.5, pobranego 19 sierpnia 2026 roku. Projekt publikuje nowe tagi niemal codziennie, dlatego należy sprawdzić używany tag zamiast polegać na treści tej strony po miesiącu. 12 października 2026 roku strona została ponownie sprawdzona pod kątem aktualnej dokumentacji projektu, gdy latest wskazywało na 0.32.9, a miejsca, w których obecne wydania zachowują się inaczej, zostały odpowiednio oznaczone. Polecenia pochodzą z repozytorium projektu pod adresem github.com/HarnessRouter/harnessrouter. Znajdowały się one w pliku README pod adresem 0.5.5; szczegóły konfiguracji znajdują się obecnie w docs/self-hosting-guide.md w tym samym repozytorium.

Czym w rzeczywistości jest Unified Harness Protocol

HarnessRouter implementuje Unified Harness Protocol (UHP), opublikowany pod adresem unifiedharnessprotocol.org. UHP opisuje sposób, w jaki produkt uruchamia zadanie w ramach harness, monitoruje jego przebieg, zarządza sesjami i plikami oraz raportuje awarie. Specyfikacja jest wersjonowana według daty. Wersja dostępna 19 sierpnia 2026 r. nosiła datę 2026-08-11. Według stanu na 12 października 2026 r. witryna wskazuje 2026-10-04 jako wersję bieżącą i nadal określa ją mianem projektu standardu, „wystarczająco stabilnego, by na nim budować, wersjonowanego w sposób umożliwiający bezpieczne wprowadzanie zmian”.

Należy uważnie interpretować sformułowanie „otwarty standard”. Ta sama firma tworzy specyfikację, implementację referencyjną oraz zestaw testów zgodności, który decyduje o tym, kto spełnia wymogi. Zasady zarządzania projektem stanowią, że żadna zmiana nie zostanie wprowadzona, dopóki wszystkie trzy elementy nie zostaną zaktualizowane jednocześnie. Według stanu na 12 października 2026 r. witryna protokołu opisuje ten zestaw jako 95 uruchamialnych testów, podczas gdy zarejestrowany przebieg referencyjny z przewodnika self-hosting, datowany na 4 września 2026 r., przeszedł 64 testy, co oznacza, że sama liczba testów nadal ulega zmianie. Jest to typowe dla tak młodego protokołu, a licencja Apache-2.0 pozwala na fork dowolnej jego części. Oznacza to również, że UHP nie jest jeszcze standardem wielodostawcowym. Należy traktować go jako protokół w fazie rozwoju: użyteczny, dynamiczny i taki, z którego własny kod powinien móc zrezygnować bez konieczności przepisywania całości.

Wymagania wstępne

Docker oraz około 4 GB wolnego miejsca na dysku. Wymagany jest również klucz API od dostawcy modelu, za którego usługi uiszczana jest opłata. Obraz zajmuje około 700 MB, a pozostałe miejsce jest przeznaczone na CLI agentów oraz obszary robocze, w których zapisują one dane. Obraz nie zawiera wbudowanego modelu ani klucza próbnego, dlatego zadania kończą się niepowodzeniem do momentu połączenia z dostawcą. HarnessRouter jest udostępniany na licencji Apache-2.0. CLI agentów nie podlegają tej licencji, dlatego są pobierane przy pierwszym uruchomieniu, zamiast być dostarczanymi wewnątrz obrazu.

Uruchomienie HarnessRouter za pomocą jednego polecenia docker run

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

Następnie należy monitorować uruchamianie kontenera. Pierwszy start trwa długo, a dziennik zdarzeń wyjaśnia przyczynę tego stanu.

docker logs -f harnessrouter

Podczas pracy widoczne będą linie o następującej treści:

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

Należy zaczekać na ready on :3000. Obecny przewodnik wskazuje, że konsola potrzebuje około pół minuty po wyświetleniu tej linii, zanim http://localhost:3000 zacznie odpowiadać. Zainstalowane narzędzia CLI są buforowane w wolumenie, więc kolejne uruchomienia są zazwyczaj znacznie szybsze. Backend dodany później lub taki, którego instalacja wcześniej się nie powiodła, może jednak ponownie wywołać proces instalacji.

Z tego pobierania wynikają dwa fakty, które mają istotne znaczenie na serwerze VPS. Po pierwsze, pierwsze uruchomienie wymaga dostępu do sieci zewnętrznej. Obraz nie jest samowystarczalny, więc serwer z aktywnym filtrem ruchu wychodzącego lub brakiem trasy do Internetu nie pobierze agentów CLI. Na testowanym tutaj 0.5.5 objawiało się to brakiem komunikatu ready on :3000, co jest mylącym punktem diagnostycznym, ponieważ docker pull zadziałało poprawnie. Obecne wydania traktują nieudaną instalację jako błąd niekrytyczny i wskazują go w dzienniku, dlatego należy sprawdzić, które backendy zostały pominięte w linii backends available:. Po drugie, instalowane jest oprogramowanie stron trzecich na warunkach określonych przez te strony. Claude Code podlega warunkom firmy Anthropic, a Hermes warunkom swojego dostawcy, dlatego przed komercyjnym użyciem należy zapoznać się z oboma regulaminami.

-v harnessrouter:/data tworzy nazwany wolumen Docker. Wszystkie trwałe dane znajdują się w /data: bazy danych SQLite, przechowywane pliki, magazyn kluczy oraz obszary robocze agentów. Usunięcie tego wolumenu oznacza usunięcie instancji, w tym kluczy dostawców oraz wszystkich transkrypcji. Kopię zapasową należy wykonać przy zatrzymanym kontenerze, ponieważ kopiowanie bazy danych SQLite w trakcie zapisu może skutkować plikiem, którego nie da się otworzyć. Ta sama zasada zatrzymania przed kopiowaniem dotyczy każdego kontenera stanowego na serwerze, choć szczegóły różnią się w zależności od usługi, ponieważ PhotoPrism i Immich wymagają własnych poleceń tworzenia kopii zapasowych.

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

Wariant compose oraz linia wymagająca zmiany

Repozytorium zawiera plik compose. Publikuje on "3000:3000", co oznacza wszystkie interfejsy na hoście. Zmień tę linię przed uruchomieniem na publicznym serwerze.

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:

Dwie rzeczy różnią się od wersji upstream: adres powiązania (bind address) oraz przypięta wersja zamiast latest. Przypinanie wersji jest istotne, ponieważ między 9 a 18 sierpnia 2026 roku wydano szesnaście wersji, a tempo nie zwalnia: tylko 12 października 2026 roku do Docker Hub trafiło pięć tagów przedpremierowych 0.33.0. Środowisko uruchomieniowe agenta, które zmienia się w trakcie pracy, jest trudne w debugowaniu. Przypnij bieżące wydanie zamiast kopiować 0.5.5 z tej strony; 12 października 2026 roku była to wersja 0.32.9. Następnie skopiuj plik środowiskowy, zablokuj jego uprawnienia i uruchom usługę.

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

.env przechowuje klucz dostawcy w postaci zwykłego tekstu, dlatego tryb 600 jest minimum. Jeśli podkomenda docker compose jest nieznana, ściąga poleceń Docker Compose zawiera zestawienie codziennie używanych operacji.

Dlaczego port jest publikowany na 127.0.0.1, a nie na 0.0.0.0

-p 3000:3000 publikuje port na każdym interfejsie dostępnym na hoście. -p 127.0.0.1:3000:3000 publikuje go wyłącznie na interfejsie zwrotnym (loopback), co oznacza, że jedyną drogą dostępu jest połączenie bezpośrednio z poziomu VPS. Kontener zawsze nasłuchuje na porcie 3000 wewnątrz, więc modyfikacji podlega lewa strona zapisu. Sprawdź bieżącą konfigurację:

docker port harnessrouter
sudo ss -ltnp | grep 3000

ss wyświetlenie 127.0.0.1:3000 jest poprawne. 0.0.0.0:3000 oznacza, że konsola jest wystawiona na publiczny Internet. W tym przypadku jest to bardziej ryzykowne niż w większości aplikacji self-hosted, ponieważ konsola tworzy środowiska uruchomieniowe, odczytuje wszystkie transkrypty, uruchamia agentów oraz zapewnia im dostęp do powłoki i rzeczywistego systemu plików w ich obszarze roboczym. Przechowuje ona również klucz dostawcy, który został użyty do połączenia. Każdy, kto uzyska dostęp do niezabezpieczonej konsoli, może odczytać Twoją pracę, wykonywać polecenia i zużywać Twój klucz.

Firewall hosta nie chroni przed tym zagrożeniem. Docker publikuje porty poprzez wpisywanie własnych reguł bezpośrednio do tablicy nat jądra systemu, a reguły te są sprawdzane przed łańcuchem zarządzanym przez ufw. W rezultacie opublikowany port pozostaje osiągalny nawet wtedy, gdy sudo ufw status wskazuje, że dostęp jest zabroniony. Testy należy przeprowadzać z innej maszyny, a nie z poziomu VPS, w przeciwnym razie wynik testu będzie niemiarodajny. Jest to ta sama lekcja, co w przypadku uruchamiania dsh headless na porcie 3080: powiąż usługę z interfejsem zwrotnym, a następnie świadomie zdecyduj, w jaki sposób będziesz uzyskiwać do niej dostęp.

Zmiana domyślnych danych logowania przed wykonaniem jakichkolwiek innych czynności

Zaloguj się pod adresem http://localhost:3000, używając nazwy użytkownika harnessrouter oraz hasła harnessrouter. Te dane uwierzytelniające są podane w pliku README, ponieważ stanowią jedynie wartości zastępcze, a nie poufne sekrety; kontener wyświetla ostrzeżenie przy każdym uruchomieniu, dopóki nie zostaną one zmienione:

using the DEFAULT password. Set HR_AUTH_PASSWORD, or change it from the profile page, before exposing this instance.

Zmień je na stronie profilu (Profile) lub ustaw w momencie uruchamiania w przypadku wdrożeń skryptowych. Zmienne HR_AUTH_USER oraz HR_AUTH_PASSWORD nadpisują wartości domyślne.

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

Funkcja resetowania hasła przez e-mail nie istnieje, ponieważ system nie posiada wbudowanego mechanizmu obsługi kont ani serwera pocztowego. W przypadku utraty hasła należy usunąć plik autoryzacji w wolumenie i zrestartować kontener, a następnie ponownie zalogować się przy użyciu danych domyślnych.

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

Zmienna HR_AUTH_DISABLED=1 całkowicie usuwa bramkę logowania. Przewodnik self-hostingowy określa to rozwiązanie jako „uzasadnione wyłącznie na maszynie, do której nikt inny nie ma dostępu”. Serwer VPS z publicznym adresem IP nie jest taką maszyną, dlatego należy pozostawić bramkę aktywną, chyba że usługa jest uruchamiana na komputerze osobistym.

Sprawdź wersję, ponieważ starsze wydania nie posiadają bramki uwierzytelniania

To jest etap wymagający szczególnej uwagi. Wersje 0.1.x oraz 0.2.0 zostały wydane całkowicie bez bramki uwierzytelniania: każda osoba, która uzyskała dostęp do portu 3000, automatycznie uzyskiwała dostęp do konsoli. Wersja 0.3.0 była pierwszym wydaniem wprowadzającym logowanie. Starsze tagi są nadal publikowane i możliwe do pobrania według stanu na 12 października 2026, więc stary przypięty tag lub plik compose skopiowany od współpracownika może obecnie wystawić niezabezpieczoną konsolę na publicznym porcie.

Według stanu na 19 sierpnia 2026 najnowszym opublikowanym tagiem był 0.5.5, datowany na 18 sierpnia 2026. W dniu 12 października 2026 tag latest wskazywał na 0.32.9, wypchnięty 11 października 2026, przy czym wersje kandydujące 0.33.0 były już opublikowane równolegle. Sprawdź posiadaną wersję, a następnie porównaj ją z listą tagów w Docker Hub:

docker image ls harnessrouter/harnessrouter

Wszystkie wersje poniżej 0.3.0 należy wymienić natychmiast, bez odkładania tego w czasie. W przypadku wersji równej lub wyższej od niej nadal konieczna jest zmiana hasła, ponieważ domyślne hasło oraz jego brak są dla osoby skanującej port 3000 tożsame. Nie należy traktować numerów wersji podanych na tej stronie jako aktualnych. Były one poprawne w podanych datach, a projekt rozwija się dynamicznie.

Podłączanie dostawcy

Nic nie zadziała, dopóki nie zostanie podłączony dostawca modelu. Można go dodać na stronie Integrations w konsoli lub przekazać do docker run w środowisku. Wartość jest w formacie JSON, więc należy ją ująć w cudzysłów w powłoce:

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

.env.example definiuje jedną zmienną połączenia dla każdej rodziny dostawców: HR_SECRET_GLOBAL_HARNESS_CONN_ANTHROPIC dla backendu claude-code, HR_SECRET_GLOBAL_HARNESS_CONN_OPENAI dla backendu codex, HR_SECRET_GLOBAL_HARNESS_CONN_GOOGLE dla backendu gemini oraz HR_SECRET_GLOBAL_HARNESS_CONN_CUSTOM dla dowolnego punktu końcowego zgodnego z OpenAI, gdzie kierowany jest agregator lub własny serwer inferencyjny. Odpowiadające im zmienne HR_SECRET_GLOBAL_HARNESS_POLICY_CLAUDE, HR_SECRET_GLOBAL_HARNESS_POLICY_CODEX oraz HR_SECRET_GLOBAL_HARNESS_POLICY_HERMES określają, z którego połączenia domyślnie korzysta dany backend; dla każdego backendu istnieje również jedna zmienna polityki. HR_SECRET_KEY jest osobnym elementem. .env.example nadal opisuje ją jako wymaganą wyłącznie do podłączenia bazy danych do agenta, a bieżący przewodnik zaleca również ustawienie jej przed podłączeniem miejsca docelowego HarnessRouter Cloud, a następnie zachowanie tego samego klucza podczas restartów i aktualizacji.

HR_BACKENDS wybiera, które backendy mają zostać zainstalowane i załadowane, tak jak w HR_BACKENDS=claude,codex,hermes. Jeśli zmienna pozostanie nieustawiona, bieżące wydania instalują znacznie dłuższą, domyślną listę około dwudziestu czterech backendów, od claude, codex i hermes po opencode, gemini, goose i inne, więc ograniczenie tej listy oszczędza miejsce na dysku i skraca czas pierwszego uruchomienia. Bieżący przewodnik dotyczący self-hostingu zaleca, aby „pominąć dowolny z nich w HR_BACKENDS, jeśli nie będzie używany”, a jego własny, odchudzony przykład to HR_BACKENDS=opencode, który całkowicie pomija Hermes. Backend, którego instalacja zakończy się niepowodzeniem, nie powoduje krytycznego błędu: pozostałe nadal działają, a zadanie przypisane do niezainstalowanego backendu kończy się niepowodzeniem przy pierwszej próbie, podczas gdy dziennik kontenera wskazuje, która instalacja zawiodła. Starsze wydania były mniej wyrozumiałe. Plik 0.5.5 README testowany w tym miejscu zawierał znany problem, w którym każda wartość pomijająca hermes powodowała natychmiastowe wyjście kontenera ze statusem 1 bez komunikatu o błędzie, dlatego w tak starych wersjach należy pozostawić HR_BACKENDS nieustawione lub wykonać aktualizację. Jeśli Hermes jest jedynym wymaganym harness, uruchomienie agenta Hermes na własnym VPS stanowi mniejsze wdrożenie.

Wywoływanie API bez użycia konsoli

Konsola jest opcjonalna. To samo API obsługuje oba interfejsy i korzysta z kontraktu w stylu Responses. Najpierw należy się zalogować, aby uzyskać plik cookie sesji:

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

Następnie należy wysłać zadanie, określając harness w metadata.harness_id oraz model faktycznie udostępniany przez połączonego dostawcę:

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}'

Obiekt JSON zawierający blok wyjściowy oraz liczbę tokenów oznacza, że harness został uruchomiony. Zmiana harness_id z codex na claude-code wysyła to samo żądanie do innego harnessa, a ta możliwość zamiany jest głównym powodem istnienia tego oprogramowania. Należy zwrócić uwagę, że identyfikator to claude-code, mimo że nazwa backendu w HR_BACKENDS oraz zmienna polityki to claude. Powyższe niestandardowe połączenie służy do wskazania harnessowi punktu końcowego zgodnego z OpenAI, który jest już hostowany, w sposób opisany w samodzielnie hostowany harness DeepSeek na VPS.

Dostęp z laptopa bez publikowania portu

Istnieją dwa sposoby, z których żaden nie wymaga otwierania surowego portu na 0.0.0.0.

Tunel SSH jest najtańszym rozwiązaniem i nie wymaga instalacji żadnego oprogramowania na serwerze. Przekierowuje on lokalny port na Twoim komputerze na adres loopback serwera VPS.

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

Pozostaw to połączenie aktywne i otwórz http://localhost:3000 w przeglądarce. Jeśli SSH wyświetli komunikat bind: Address already in use, oznacza to, że port 3000 jest już zajęty na Twoim laptopie. Wybierz inny port lokalny za pomocą -L 3100:127.0.0.1:3000 i przejdź pod adres portu 3100.

Terminujący reverse proxy jest rozwiązaniem, gdy dostęp mają uzyskać inne osoby. Proxy obsługuje certyfikat TLS (transport layer security) i przekazuje ruch na adres loopback. Przewodnik self-hosting zawiera przykładową konfigurację Caddy:

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 to linia, o której często zapominają użytkownicy. Agent przesyła tokeny strumieniowo przez kilka minut, a proxy, które buforuje odpowiedź, przetrzymuje te tokeny do momentu zakończenia transmisji. W efekcie konsola wydaje się zawieszona, a następnie wyświetla całą zawartość naraz. Odpowiednikiem w Nginx jest proxy_buffering off; umieszczone wewnątrz bloku location. Niezależnie od wyboru, nazwa DNS powinna wskazywać na proxy, a kontener powinien działać na adresie loopback. Artykuł Porównanie Nginx, Caddy i Traefik jako reverse proxy zawiera informacje pomocne w dopasowaniu rozwiązania do Twojego serwera.

Uruchamianie jako dedykowany użytkownik, a nie jako root

Demon Docker działa z uprawnieniami roota, a członkostwo w grupie docker jest równoważne z posiadaniem uprawnień roota, ponieważ członek grupy może uruchomić kontener montujący system plików hosta. Zatem „dodanie zespołu do grupy docker” oznacza nadanie uprawnień roota na maszynie, na której przechowywany jest klucz dostawcy.

Wersja uproszczona: należy utworzyć konto serwisowe, które będzie właścicielem pliku compose oraz .env, i przechowywać te pliki poza jakimkolwiek współdzielonym katalogiem domowym.

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

Nie należy próbować osiągnąć tego celu poprzez dodanie --user do docker run lub user: do pliku compose. Obecny przewodnik wskazuje, że kontener musi uruchamiać się jako root, a od wersji 0.8.2 odmawia uruchomienia w jakikolwiek inny sposób, co jest odnotowane w jednym wierszu dziennika.

Wersja bardziej rygorystyczna to rootless Docker, w której sam demon działa jako użytkownik bez uprawnień administracyjnych. Wymaga to pakietu uidmap dla newuidmap i newgidmap, a także co najmniej 65536 podrzędnych identyfikatorów UID w plikach /etc/subuid oraz /etc/subgid dla danego użytkownika. Pakiet uidmap znajduje się w repozytoriach Ubuntu, ale docker-ce-rootless-extras nie: jest on dostarczany z własnego repozytorium apt firmy Docker pod adresem download.docker.com, które jest dodawane podczas instalacji silnika Docker. Jeśli silnik nie został zainstalowany z tego repozytorium, polecenie grep -rl download.docker.com /etc/apt/sources.list.d/ nie zwróci żadnych wyników, a poniższa instalacja nie znajdzie pakietu.

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

Opcja loginctl enable-linger nie jest tutaj opcjonalna. Bez niej instancja systemd użytkownika zatrzymuje się po zamknięciu ostatniej sesji, co powoduje wyłączenie kontenera po wylogowaniu. Wynik należy potwierdzić za pomocą docker info, co wyświetli rootless w sekcji Security Options. Tryb rootless nie może wiązać portów poniżej 1024 bez dodatkowej konfiguracji, co w tym przypadku nie ma znaczenia, ponieważ port 3000 znajduje się powyżej tej wartości. Konfiguracja samego konta została opisana w tworzenie użytkowników o minimalnych uprawnieniach na VPS.

Co ulega awarii i co zobaczysz

Kontener wyłącza się sekundę po uruchomieniu, a logi są puste. docker ps -a pokazuje Exited (1). W przypadku 0.5.5 i innych starszych tagów jest to wspomniany wyżej problem HR_BACKENDS: w wartości pominięto hermes. Przywróć ją lub wykonaj aktualizację. Bieżące wydania nie kończą się w ten sposób, więc w przypadku nowszego tagu sprawdź ostatnią linię docker logs: od wersji 0.8.2 kontener uruchomiony z --user wyłącza się, wyświetlając komunikat o konieczności uruchomienia jako root.

Pierwsze uruchomienie nigdy się nie kończy. Log zatrzymuje się po linii installing, a ready on :3000 nigdy się nie pojawia. Serwer nie może połączyć się z siecią, aby pobrać CLI agentów, ponieważ nie znajdują się one w obrazie. W bieżących wydaniach objaw jest łagodniejszy – w logu wymienione są nieudane instalacje, których brakuje w linii backends available:. W obu przypadkach napraw trasę wychodzącą lub ustawienia proxy, a następnie zrestartuj usługę.

Konsola ładuje się, ale każde zadanie kończy się błędem. Żaden dostawca nie jest połączony. Obraz nie zawiera wbudowanego modelu ani darmowego planu, więc świeża instancja pozwala się zalogować, ale nie może niczego uruchomić.

Konsola zawiesza się w trakcie generowania odpowiedzi za proxy. Dane wyjściowe pojawiają się w jednym bloku dopiero po zakończeniu tury. Jest to spowodowane buforowaniem odpowiedzi. Ustaw flush_interval -1 w Caddy lub proxy_buffering off; w Nginx.

Brak dostępu z laptopa mimo aktywnego tunelu. Uruchom docker port harnessrouter na serwerze. Jeśli polecenie nic nie zwraca, kontener nie publikuje żadnych portów, co oznacza, że został uruchomiony bez flagi -p.

Czy warto to uruchamiać?

Warto to uruchamiać, jeśli faktycznie używasz więcej niż jednego narzędzia typu harness i potrzebujesz jednego punktu końcowego oraz jednego magazynu poświadczeń zamiast trzech dla każdego z nich. Warto to również uruchomić, jeśli budujesz na tym produkt i chcesz, aby harness był wartością konfiguracyjną, a nie wymagał przepisywania kodu. To właśnie zapewnia UHP, przy zastrzeżeniu wspomnianym powyżej, dotyczącym wczesnego etapu rozwoju tego protokołu.

Nie warto tego uruchamiać, jeśli używasz tylko jednego narzędzia typu harness. Instalacja tego CLI na serwerze oznacza mniej ruchomych elementów, a między użytkownikiem a narzędziem nie znajduje się żaden proces logowania. Jest to również niewłaściwe rozwiązanie, jeśli celem jest współpraca kilku agentów przy jednym zadaniu, a nie jedno API przed kilkoma harnessami; do tego służy inne narzędzie: zobacz wieloagentowy harness, taki jak Omnigent. Niezależnie od wyboru, zasady wdrażania pozostają niezmienne. Powiązanie z interfejsem loopback, zmienione hasło, przypięty tag w wersji 0.3.0 lub nowszej oraz dedykowany użytkownik.

FAQ

Czy publikowanie HarnessRouter na porcie 3000 jest bezpieczne?

Nie. Konsola tworzy harnessy, odczytuje wszystkie transkrypty, uruchamia agentów z dostępem do powłoki i systemu plików oraz przechowuje klucz dostawcy, który został podłączony, więc otwarty port naraża wszystkie te zasoby. Należy publikować usługę na interfejsie zwrotnym (loopback) za pomocą -p 127.0.0.1:3000:3000 i uzyskiwać do niej dostęp przez tunel SSH lub reverse proxy z terminacją TLS. Firewall hosta sam w sobie nie wystarcza: Docker zapisuje własne reguły w tablicy nat jądra, więc opublikowany port odpowiada na zapytania z Internetu, nawet jeśli ufw wskazuje, że ruch jest blokowany. Należy zweryfikować to za pomocą sudo ss -ltnp | grep 3000, co powinno zwrócić 127.0.0.1:3000.

W której wersji HarnessRouter dodano bramkę logowania?

0.3.0. Wersje 0.1.x oraz 0.2.0 były wydawane bez żadnego uwierzytelniania, a na dzień 12 października 2026 obie są nadal publikowane i możliwe do pobrania, więc każdy, kto ich używa, polega wyłącznie na tym, że nikt nie odkryje portu. Na dzień 19 sierpnia 2026 najnowszym tagiem był 0.5.5, datowany na 18 sierpnia 2026; 12 października 2026 latest wskazywał na 0.32.9. Należy uruchomić docker image ls harnessrouter/harnessrouter, aby sprawdzić posiadaną wersję, porównać ją z listą tagów w Docker Hub, a nie z tą stroną, oraz zmienić domyślne hasło nawet w aktualnej wersji.

Dlaczego kontener wyłącza się natychmiast po ustawieniu HR_BACKENDS?

W aktualnym wydaniu nie powinno to mieć miejsca. Przewodnik self-hosting zaleca pominięcie każdego backendu, który nie będzie używany, a błąd instalacji backendu nie jest krytyczny. Wyłączanie się było znanym problemem w starszych wydaniach, w tym 0.5.5, na którym testowano tę stronę, gdzie każda wartość pomijająca hermes powodowała wyjście ze statusem 1 bez komunikatu o błędzie. Jeśli w docker ps -a na tak starej wersji widoczny jest komunikat Exited (1), należy przywrócić hermes, zgodnie z HR_BACKENDS=claude,codex,hermes, lub przeprowadzić aktualizację. W przypadku nowszego taga należy przeczytać docker logs: od wersji 0.8.2 kontener uruchomiony z --user wyłącza się z jedną linią komunikatu informującą, że musi zostać uruchomiony jako root.

Czy HarnessRouter wymaga dostępu do Internetu przy pierwszym uruchomieniu?

Tak. CLI agentów są pobierane przy pierwszym uruchomieniu, zamiast być dostarczanymi w obrazie, ponieważ każdy z nich posiada własną licencję. Na 0.5.5 maszyna bez trasy wyjściowej wyświetlała linie installing, a następnie nigdy nie łączyła się z ready on :3000; aktualne wydania wskazują nieudane instalacje bezpośrednio w logach. Zainstalowane pliki CLI są buforowane na wolumenie, więc kolejne uruchomienia są zazwyczaj szybsze i nie wymagają sieci poza połączeniem z dostawcą modelu, chyba że włączony zostanie nowy backend lub poprzednia instalacja zakończyła się niepowodzeniem.

Utraciłem hasło do konsoli. Jak odzyskać dostęp?

Nie ma opcji resetowania hasła przez e-mail, ponieważ nie istnieje system kont ani serwer pocztowy. Należy zatrzymać kontener, usunąć /data/selfhost-auth.json z wolumenu, uruchomić go ponownie, zalogować się przy użyciu domyślnych danych uwierzytelniających i ustawić nowe hasło na stronie profilu. Przy kontenerze i wolumenie o nazwie harnessrouter, sekwencja poleceń to docker stop harnessrouter, następnie docker run --rm -v harnessrouter:/data alpine rm -f /data/selfhost-auth.json, a potem docker start harnessrouter.

#harnessrouter#agent-harness#docker#self-hosting#api