Hermes Agent: Headless Server + Remote Desktop-configuratie

Headless Hermes-server met toegang tot de remote desktop

Inhoud

Het uitvoeren van de Hermes Agent op een headless server terwijl je vanaf een desktopclient op een andere machine verbinding maakt, vereist twee serverprocessen en één clientverbinding.

De architectuur scheidt de Hermes-backend in twee serverprocessen en één clientinterface. Het hermes serve-backend behandelt de API- en dashboardverbindingen, terwijl het hermes gateway run-proces de berichtkanalen onafhankelijk beheert. De desktopclient maakt verbinding met het serve-backend, niet met de gateway.

flowchart LR subgraph Server["HEADLESS SERVER"] serve["hermes serve
--host 0.0.0.0
:9119"] gateway["hermes gateway run
Telegram, Discord, Slack"] end subgraph Client["DESKTOP PC"] desktop["hermes desktop
(WebSocket-verbinding)"] end desktop <--->|WebSocket| serve gateway -.->|Deelt ~/.hermes/| serve

Twee processen op de server, één app op de client. Beide serverprocessen delen dezelfde ~/.hermes/-configuratie, vaardigheden, geheugen en sessies. Cronjobs worden uitgevoerd op de server waar de gateway draait.

Hermes Agent headless server architectuur

Voor installatie, providerconfiguratie en initiële opstartprocedure begint u met de Hermes AI Assistant — Installatie, Configuratie, Workflow en Probleemoplossing.

De headless server instellen

1. Authenticatie configureren

Basic auth biedt voldoende bescherming voor een vertrouwd LAN. Voeg referenties toe aan het environment-bestand:

cat >> ~/.hermes/.env << 'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=kies-een-sterk-wachtwoord
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

Het .env-bestand bevindt zich naast config.yaml onder ~/.hermes/. Hermes lost configuratie op met CLI-overrides eerst, dan config.yaml, dan .env, en daarna de ingebouwde standaardwaarden. Geheime waarden (secrets) horen in .env.

2. De backend starten

Start het serve-backend op alle interfaces:

hermes serve --host 0.0.0.0 --port 9119

De backend luistert op poort 9119 en accepteert WebSocket-verbindingen van de desktopclient. Verifieer dat deze draait met een snelle statuscontrole:

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

3. Uitvoeren als systemd-service

Voor een persistente server die reboots overleeft, installeert u een systemd-service op gebruikersniveau. Maak het unit-bestand aan op /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

Herlaad de daemon, schakel de service in en start deze:

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

Controleer de servicestatus:

systemctl --user status hermes-serve

4. De gateway starten

De gateway is een apart proces dat de berichtkanalen beheert — Telegram, Discord, Slack en anderen. Start deze onafhankelijk:

hermes gateway run

De gateway en het serve-backend zijn twee aparte processen. De gateway beheert sessies, voert cronjobs uit en routeert berichten. Het serve-backend biedt de API-interface voor desktop- en webdashboardverbindingen. Ze delen dezelfde home-directory, maar draaien onafhankelijk.

Voor de volledige lijst met gateway-commando’s en subcommando’s, zie het Hermes Agent CLI-cheat sheet. Als uw primaire interface mobiel berichtenverkeer is, combineer deze opstelling met Hermes Spraakbesturing vanaf uw Telefoon voor spraakgestuurde workflows bovenop hetzelfde gateway-proces.

5. De backend verifiëren

Bevestig dat de backend reageert en dat authenticatie actief is:

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

Verwachte uitvoer:

true
"basic"

Als authenticatie niet is ingeschakeld, toont de reactie false voor auth_required. Controleer of het .env-bestand de juiste variabelen bevat en of de service is herstart na configuratiewijzigingen.

Verbinding maken vanaf de desktopclient

Optie A: Hermes Desktop App

Installeer Hermes Desktop vanaf de officiële site. Start de app, ga naar Instellingen → Gateway → Remote gateway en voer het serveradres in:

http://<server-ip>:9119

Meld u aan met de gebruikersnaam en het wachtwoord die u op de server hebt geconfigureerd.

Alternatief stelt u de externe URL in via een environment-variabele:

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

Optie B: Webdashboard

Open http://<server-ip>:9119 in een browser en meld u aan met de basic auth-referenties. Het webdashboard biedt een browsergebaseerde interface naar de Hermes-backend zonder dat een desktopinstallatie nodig is.

Optie C: CLI

Configureer vanaf de terminal van de desktop-PC de externe URL via de instellingen van de desktopapp of de HERMES_DESKTOP_REMOTE_URL-environment-variabele. De CLI-interface maakt verbinding via dezelfde WebSocket-kanaal als de desktopapp.

Netwerk- en beveiligingsaspecten

Scenario Aanbeveling
Vertrouwd LAN --host 0.0.0.0 + basic auth
Blootgesteld aan internet Gebruik Tailscale (--host <tailscale-ip>) of OAuth-provider
Firewall Open poort 9119 TCP op de server

Voor een vertrouwd lokaal netwerk is basic auth op 0.0.0.0 adequate. Als de server aan het internet is blootgesteld, gebruikt u Tailscale om te binden aan het Tailscale IP in plaats van 0.0.0.0, of configureert u een OAuth-provider voor sterkere authenticatie. Open altijd poort 9119 TCP in de firewall van de server wanneer de backend externe verbindingen moet accepteren.

Belangrijke procesonderscheidingen

Het begrijpen van de scheiding tussen de twee serverprocessen voorkomt veelvoorkomende configuratiefouten:

  • hermes serve — De backend waarnaar de desktopapp en het webdashboard verbinding maken. Behandelt de API-interface en WebSocket-verbindingen.
  • hermes gateway run — Het proces dat Telegram, Discord, Slack en andere berichtkanalen behandelt. Beheert sessies, voert cronjobs uit en routeert berichten.
  • Dit zijn twee aparte processen op de server. Ze delen ~/.hermes/-configuratie, vaardigheden, geheugen en sessies, maar draaien onafhankelijk.
  • Cronjobs worden uitgevoerd op de server waar de gateway draait.
  • Profielen, vaardigheden en geheugen worden aan de serverzijde geconfigureerd. De client maakt verbinding met de reeds geconfigureerde backend.

Voor profielgestuurde configuratie en vaardigheden die zijn afgestemd op verschillende productie-rollen, zie Hermes AI Assistant Vaardigheden voor Echte Productie-Opstellingen.

Probleemoplossing

Desktop kan geen verbinding maken met de server

  1. Verifieer dat de backend draait: systemctl --user status hermes-serve
  2. Controleer of de poort open is: ss -tlnp | grep 9119
  3. Test vanaf de server: curl -s http://localhost:9119/api/status
  4. Test vanaf de clientmachine: curl -s http://<server-ip>:9119/api/status
  5. Als de clienttest faalt, controleer de firewall-regels: sudo ufw status of sudo iptables -L

Authenticatie faalt

  1. Bevestig dat het .env-bestand de juiste rechten heeft: ls -la ~/.hermes/.env (moet 600 zijn)
  2. Verifieer dat het secret is gegenereerd: grep HERMES_DASHBOARD_BASIC_AUTH_SECRET ~/.hermes/.env
  3. Start de service opnieuw na configuratiewijzigingen: systemctl --user restart hermes-serve

Gateway reageert niet op berichten

De gateway is een apart proces van de backend. Als de desktop verbinding maakt, maar berichtplatforms niet werken:

  1. Controleer gateway-status: hermes gateway status
  2. Start de gateway indien gestopt: hermes gateway start
  3. Bekijk logs: hermes logs gateway -f

Referenties

Dit artikel is deel van de AI-systemen-cluster, die zelf gehoste assistenten, retrieval-architectuur, lokale LLM-infrastructuur en observability behandelt.

Abonneren

Ontvang nieuwe berichten over systemen, infrastructuur en AI-engineering.