Agent Hermes: konfiguracja bezserwerowa + zdalny pulpit

Uruchamianie Hermes Agent na serwerze headless (bez interfejsu graficznego) z jednoczesnym połączeniem klienta desktopowego z innego komputera wymaga uruchomienia dwóch procesów po stronie serwera oraz jednego połączenia klienckiego.

Architektura dzieli backend Hermes na dwa procesy po stronie serwera i jeden interfejs po stronie klienta. Backend hermes serve obsługuje połączenia API i panelu sterowania, podczas gdy proces hermes gateway run niezależnie zarządza kanałami komunikacyjnymi. Klient desktopowy łączy się z backendem serwera, a nie z bramką (gateway).

Dwa procesy na serwerze, jedna aplikacja po stronie klienta. Obie procesy serwera współdzielą ten sam katalog konfiguracji ~/.hermes/, umiejętności (skills), pamięć i sesje. Zadania Cron są wykonywane na serwerze, gdzie działa bramka (gateway).

Aby rozpocząć instalację, konfigurację dostawcy (provider) i początkową konfigurację, skorzystaj z przewodnika Hermes AI Assistant — Instalacja, konfiguracja, przepływ pracy i rozwiązywanie problemów.

Konfiguracja serwera headless

1. Konfiguracja uwierzytelniania

Podstawowe uwierzytelnianie (Basic Auth) zapewnia wystarczającą ochronę zaufanej sieci LAN. Dodaj dane uwierzytelniające do pliku środowiskowego:

cat >> ~/.hermes/.env << 'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

Plik .env znajduje się obok config.yaml w katalogu ~/.hermes/. Hermes rozwiązuje konfigurację w kolejności: nadpisania z wiersza poleceń (CLI), następnie config.yaml, następnie .env, a na końcu domyślne ustawienia wbudowane. Tajne dane (secrets) powinny znajdować się w pliku .env.

2. Uruchomienie backendu

Uruchom backend serwera na wszystkich interfejsach:

hermes serve --host 0.0.0.0 --port 9119

Backend nasłuchuje na porcie 9119 i akceptuje połączenia WebSocket od klienta desktopowego. Zweryfikuj, czy działa, wykonując szybką kontrolę statusu:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'
# Oczekiwany wynik: true  "basic"

3. Uruchamianie jako usługa systemd

Aby utrzymać serwer działający nawet po restarcie, zainstaluj usługę systemd na poziomie użytkownika. Stwórz plik jednostki (unit file) w /etc/systemd/user/hermes-serve.service:

[Unit]
Description=Hermes Agent Serve Backend

[Service]
EnvironmentFile=%h/.hermes/.env
ExecStart=/home/rg/.hermes/hermes-agent/venv/bin/python -m hermes_cli.main serve --host 0.0.0.0 --port 9119
Restart=on-failure

[Install]
WantedBy=default.target

Przeładuj daemon, włącz usługę i ją uruchom:

systemctl --user daemon-reload
systemctl --user enable hermes-serve
systemctl --user start hermes-serve

Sprawdź status usługi:

systemctl --user status hermes-serve

4. Uruchomienie bramki (gateway)

Bramka (gateway) to osobny proces obsługujący kanały komunikacyjne – Telegram, Discord, Slack i inne. Uruchom ją niezależnie:

hermes gateway run

Bramka i backend serwera to dwa osobne procesy. Bramka zarządza sesjami, uruchamia zadania Cron i kieruje wiadomości. Backend serwera zapewnia interfejs API dla połączeń desktopowych i panelu webowego. Współdzielą ten sam katalog domowy, ale działają niezależnie.

Pełną listę poleceń i podpoleceń bramki znajdziesz w Ściągnicy CLI Hermes Agent. Jeśli głównym interfejsem jest komunikacja mobilna, połącz tę konfigurację z Kontrola głosowa Hermes z telefonu w celu uzyskania przepływów pracy opartych na głosie na bazie tego samego procesu bramki.

5. Weryfikacja backendu

Potwierdź, że backend odpowiada i uwierzytelnianie jest aktywne:

curl -s http://localhost:9119/api/status | jq '.auth_required, .auth_providers'

Oczekiwany wynik:

true
"basic"

Jeśli uwierzytelnianie nie jest włączone, odpowiedź pokaże false dla auth_required. Sprawdź, czy plik .env zawiera poprawne zmienne oraz czy usługa została uruchomiona ponownie po zmianach konfiguracji.

Połączenie z klienta desktopowego

Opcja A: Aplikacja Hermes Desktop

Zainstaluj Hermes Desktop ze strony oficjalnej. Uruchom aplikację, przejdź do Ustawienia → Bramka → Zdalna bramka i wprowadź adres serwera:

http://<ip-serwera>:9119

Zaloguj się przy użyciu nazwy użytkownika i hasła skonfigurowanych na serwerze.

Alternatywnie, ustaw zdalny URL poprzez zmienną środowiskową:

HERMES_DESKTOP_REMOTE_URL=http://<ip-serwera>:9119 hermes desktop

Opcja B: Panel webowy

Otwórz http://<ip-serwera>:9119 w przeglądarce i zaloguj się przy użyciu danych uwierzytelniających Basic Auth. Panel webowy zapewnia interfejs oparty na przeglądarce do backendu Hermes bez konieczności instalacji aplikacji desktopowej.

Opcja C: Wiersz poleceń (CLI)

Z terminala komputera pulpitowego skonfiguruj zdalny URL poprzez ustawienia aplikacji desktopowej lub zmienną środowiskową HERMES_DESKTOP_REMOTE_URL. Interfejs CLI łączy się przez ten sam kanał WebSocket co aplikacja desktopowa.

Wymogi sieciowe i bezpieczeństwa

Dla zaufanej sieci lokalnej podstawowe uwierzytelnianie na 0.0.0.0 jest wystarczające. Jeśli serwer jest narażony na internet, użyj Tailscale do powiązania z adresem IP Tailscale zamiast 0.0.0.0, lub skonfiguruj dostawcę OAuth dla silniejszego uwierzytelniania. Zawsze otwieraj port 9119 TCP w firewallu serwera, gdy backend musi akceptować połączenia zewnętrzne.

Ważne rozróżnienia procesów

Zrozumienie rozdziału między dwoma procesami serwera zapobiega powszechnym błędom konfiguracji:

• hermes serve — Backend, z którym łączą się aplikacja desktopowa i panel webowy. Obsługuje interfejs API i połączenia WebSocket.
• hermes gateway run — Proces obsługujący Telegram, Discord, Slack i inne kanały komunikacyjne. Zarządza sesjami, uruchamia zadania Cron i kieruje wiadomości.
• Są to dwa osobne procesy na serwerze. Współdzielą konfigurację ~/.hermes/, umiejętności, pamięć i sesje, ale działają niezależnie.
• Zadania Cron są wykonywane na serwerze, gdzie działa bramka.
• Profile, umiejętności i pamięć są konfigurowane po stronie serwera. Klient łączy się z już skonfigurowanym backendem.

Aby uzyskać konfigurację opartą na profilach i umiejętnościach dostosowanych do różnych ról produkcyjnych, zobacz Umiejętności Hermes AI Assistant dla rzeczywistych środowisk produkcyjnych.

Rozwiązywanie problemów

Klient desktopowy nie może połączyć się z serwerem

1. Zweryfikuj, czy backend działa: systemctl --user status hermes-serve
2. Sprawdź, czy port jest otwarty: ss -tlnp | grep 9119
3. Przetestuj z serwera: curl -s http://localhost:9119/api/status
4. Przetestuj z maszyny klienckiej: curl -s http://<ip-serwera>:9119/api/status
5. Jeśli test klienta nie powiedzie się, sprawdź reguły firewalla: sudo ufw status lub sudo iptables -L

Uwierzytelnianie nie powiedzie się

1. Potwierdź, czy plik .env ma poprawne uprawnienia: ls -la ~/.hermes/.env (powinny być 600)
2. Zweryfikuj, czy sekret został wygenerowany: grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env
3. Uruchom ponownie usługę po zmianach konfiguracji: systemctl --user restart hermes-serve

Bramka nie odpowiada na wiadomości

Bramka to osobny proces od backendu. Jeśli klient desktopowy się łączy, ale platformy komunikacyjne nie działają:

1. Sprawdź status bramki: hermes gateway status
2. Uruchom bramkę, jeśli jest zatrzymana: hermes gateway start
3. Przeglądaj logi: hermes logs gateway -f

Bibliografia

• Dokumentacja aplikacji Hermes Agent Desktop
• Przewodnik konfiguracji Hermes Agent
• Bramka komunikacyjna Hermes Agent
• Hermes AI Assistant — Instalacja, konfiguracja, przepływ pracy i rozwiązywanie problemów
• Ściągnica CLI Hermes Agent — polecenia, flagi i skróty slash
• Umiejętności Hermes AI Assistant dla rzeczywistych środowisk produkcyjnych

Ten artykuł jest częścią klastera Systemy AI, który obejmuje samodzielnie hostowanych asystentów, architekturę pobierania, lokalną infrastrukturę LLM i obserwowalność.