Hermes Agent auf Windows VPS: Vollständige bebilderte Anleitung

Ziel dieser Architektur ist, Hermes Agent zwischen Webanwendung und einzelnen KI-Anbietern zu platzieren. Die Anwendung sieht nur einen OpenAI-kompatiblen Endpunkt, während Hermes Hauptmodell, Fallback-Anbieter und spätere Funktionen wie Websuche, Memory und Cron-Aufgaben verwaltet.

Für den Produktivbetrieb bleibt die Hermes-API an 127.0.0.1 gebunden und wird über Caddy per HTTPS veröffentlicht. DNS, TLS/Reverse-Proxy und Hermes-Prozess lassen sich dadurch getrennt prüfen.

WISECP / Webanwendung
        ↓
https://ai-api.example.com/v1
        ↓
Caddy :443
        ↓
127.0.0.1:8642
        ↓
Hermes Agent
        ↓
Hauptmodell → Fallback-Kette

Hermes lässt sich nativ über PowerShell installieren. Die Daten liegen standardmäßig im LocalAppData-hermes-Verzeichnis des Administratorprofils, darunter config.yaml, .env, auth.json, logs und sessions.

Wir verwendeten Full Setup, um Provider, Modell und Tools selbst festzulegen, und wählten anschließend OpenAI als Inference Provider.

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

hermes --version

Nach Auswahl von OpenAI Codex startet Hermes den Device-Login und zeigt URL sowie einen kurzlebigen Code. Öffnen Sie die URL, geben Sie den Code ein und autorisieren Sie das gewünschte ChatGPT/Codex-Konto.

Gerätecode, auth.json und Tokenwerte sind vertraulich und sollten nie in veröffentlichten Screenshots stehen.

https://auth.openai.com/codex/device

Nach OAuth zeigt Hermes die für das Konto verfügbaren Modelle. Modellnamen können sich ändern; verwenden Sie die aktuelle Liste Ihrer Installation.

Da dieser VPS primär als AI-API-Gateway für WISECP und eigene Webanwendungen dient, haben wir Terminal, Dateioperationen, Code Execution, Browser Automation und Computer Use zunächst deaktiviert.

Web Search, Memory oder Cron sollten später nur gezielt aktiviert werden.

hermes setup tools

hermes setup terminal

Nach der Einrichtung zeigt Hermes die Pfade für Konfiguration, .env und Daten. Aktivieren Sie den OpenAI-kompatiblen API Server über die API_SERVER-Variablen.

API_SERVER_HOST=127.0.0.1 ist entscheidend: Port 8642 wird nicht direkt öffentlich gebunden; externer Verkehr läuft später über Caddy/HTTPS.

Verwenden Sie einen langen zufälligen API_SERVER_KEY und speichern Sie ihn ausschließlich serverseitig.

notepad C:\Users\Administrator\AppData\Local\hermes\.env

API_SERVER_ENABLED=true
API_SERVER_HOST=127.0.0.1
API_SERVER_PORT=8642
API_SERVER_KEY=STARKES_ZUFAELLIGES_SECRET
API_SERVER_MODEL_NAME=hermes-agent

$bytes = New-Object byte[] 32; $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create(); $rng.GetBytes($bytes); ($bytes | ForEach-Object { $_.ToString("x2") }) -join ""

Der API Server startet zusammen mit dem Gateway. Prüfen Sie /health in einem zweiten PowerShell-Fenster, bevor Sie Caddy oder Cloudflare konfigurieren.

Eine erfolgreiche Antwort beweist, dass Hermes unabhängig von DNS und TLS auf Port 8642 lauscht.

hermes gateway

curl.exe http://127.0.0.1:8642/health

Ein Health-Check bestätigt nur die Erreichbarkeit. Senden Sie daher eine echte Anfrage an /v1/chat/completions mit API_SERVER_KEY als Bearer-Token.

In unserem Test erreichte die Anfrage OpenAI Codex, das Konto antwortete jedoch wegen erreichtem Nutzungslimit mit HTTP 429. Das ist ein Upstream-Limit und kein lokaler API-Fehler.

Ältere PowerShell/.NET-Versionen unterstützen nicht alle neuen RandomNumberGenerator-Kurzformen. Verwenden Sie bei Fehlern die byte[]-Methode.

$envDatei = "C:\Users\Administrator\AppData\Local\hermes\.env"
$apiKey = ((Get-Content $envDatei | Where-Object { $_ -like "API_SERVER_KEY=*" } | Select-Object -First 1) -replace "^API_SERVER_KEY=", "").Trim()

POST http://127.0.0.1:8642/v1/chat/completions
Authorization: Bearer API_SERVER_KEY

Unser erster Webi-Versuch schlug in einer administrativen PowerShell fehl. Das war ein Webi-Installationsproblem, kein Hermes-Fehler.

Für eine reproduzierbare Serverinstallation luden wir die offizielle Windows-Binary nach C:\Caddy und öffneten TCP 80 und 443 in der Windows-Firewall.

Für Port 8642 wurde keine Inbound-Regel erstellt; die Hermes-API bleibt nur lokal erreichbar.

New-Item -ItemType Directory -Force C:\Caddy

curl.exe -L "https://github.com/caddyserver/caddy/releases/download/v2.11.4/caddy_2.11.4_windows_amd64.zip" -o "C:\Caddy\caddy.zip"

Expand-Archive -Path "C:\Caddy\caddy.zip" -DestinationPath "C:\Caddy" -Force

New-NetFirewallRule -DisplayName "Caddy HTTP 80" -Direction Inbound -Protocol TCP -LocalPort 80 -Action Allow
New-NetFirewallRule -DisplayName "Caddy HTTPS 443" -Direction Inbound -Protocol TCP -LocalPort 443 -Action Allow

Im Caddyfile genügen Hostname und reverse_proxy-Ziel. Notepad kann die Datei als Caddyfile.txt speichern; dann findet Caddy die erwartete Datei nicht.

Entfernen Sie die Erweiterung, validieren Sie die Konfiguration und starten Sie Caddy.

ai-api.example.com {
    reverse_proxy 127.0.0.1:8642
}

Rename-Item "C:\Caddy\Caddyfile.txt" "Caddyfile"

C:\Caddy\caddy.exe validate --config C:\Caddy\Caddyfile

C:\Caddy\caddy.exe run --config C:\Caddy\Caddyfile

Erreicht die Domain Caddy, während Hermes nicht läuft, erscheint 502 Bad Gateway. dial tcp 127.0.0.1:8642 connection refused im Caddy-Log bedeutet, dass DNS/TLS weitgehend funktionieren, aber das Backend nicht erreichbar ist.

Prüfen Sie zuerst den lokalen Health-Endpunkt und starten Sie Hermes bei Bedarf neu. Arbeiten Sie nicht gleichzeitig an Cloudflare und Hermes, wenn localhost bereits fehlschlägt.

curl.exe http://127.0.0.1:8642/health

hermes gateway

Laufen Caddy und Hermes, liefert die öffentliche /health-URL die Hermes-Antwort. Der Pfad lautet nun Internet → Caddy → localhost:8642 → Hermes.

Bei Cloudflare kann DNS-only während der Origin-/Zertifikatsdiagnose hilfreich sein. Aktivieren Sie den Proxy wieder, sobald der Origin-Pfad bestätigt ist.

https://ai-api.example.com/health

Ein im PowerShell-Fenster gestarteter caddy.exe-run-Prozess endet mit dem Fenster. Registrieren Sie Caddy daher als automatisch startenden Windows-Dienst.

STATE : 4 RUNNING bestätigt den laufenden Hintergrunddienst.

sc.exe create caddy start= auto binPath= "C:\Caddy\caddy.exe run --config C:\Caddy\Caddyfile"

sc.exe failure caddy reset= 86400 actions= restart/5000/restart/5000/restart/5000

sc.exe start caddy

sc.exe query caddy

Hermes kann das Windows-Gateway über geplante Aufgaben verwalten. Der dokumentierte Ablauf registriert die Aufgabe mit hermes gateway install und verwaltet den Hintergrundprozess anschließend mit gateway start/status.

Für einen Produktiv-VPS stellen Sie die Aufgabe auf 'Ausführen, unabhängig davon, ob der Benutzer angemeldet ist' und aktivieren höchste Privilegien.

Ändern Sie den Trigger auf Systemstart. Das Administrator-Passwort wird nur lokal in der Aufgabenplanung eingegeben und gehört niemals in die Dokumentation.

hermes gateway install

hermes gateway start
hermes gateway status

schtasks /Query /TN Hermes_Gateway /V /FO LIST

Nach der Service-Konfiguration schlossen wir alle PowerShell-Fenster und der öffentliche Health-Endpunkt blieb erreichbar. Der finale Test ist ein kompletter Neustart und eine Prüfung vor dem RDP-Login.

Antwortet der Endpunkt, starten Caddy und Hermes unabhängig von einer interaktiven Sitzung.

Restart-Computer

https://ai-api.example.com/health

Hermes kann bei Rate Limits, Server-/Auth-Fehlern oder Verbindungsproblemen auf ein anderes provider:model-Paar wechseln. Testen Sie einen Custom Endpoint zuerst direkt.

Wir testeten openai/gpt-oss-20b über einen OpenAI-kompatiblen LLMGate-Endpunkt und legten anschließend den Schlüssel in .env sowie Endpoint/Modell in fallback_providers der config.yaml ab.

Mit key_env referenzieren Sie die Umgebungsvariable, ohne das Secret direkt in config.yaml zu schreiben.

LLMGATE_API_KEY=PRIVATER_API_KEY

fallback_providers:
  - provider: custom
    model: openai/gpt-oss-20b
    base_url: https://llmgate.waflare.net/v1
    key_env: LLMGATE_API_KEY

Windows PowerShell 5.1 kann JSON unter bestimmten Bedingungen mit unerwartetem Encoding senden. Bei türkischen Zeichen erhielten wir Invalid JSON in request body.

Die Umwandlung des JSON in UTF-8-Bytes und Content-Type application/json; charset=utf-8 löste den Fehler. Da Codex rate-limitiert war, bestätigte die erfolgreiche Antwort zugleich den Fallback.

$body = @{ model = "hermes-agent"; messages = @(@{ role = "user"; content = "Schreibe eine kurze VPS-Hosting-SEO-Beschreibung." }); max_tokens = 100 } | ConvertTo-Json -Depth 5
$utf8Body = [System.Text.Encoding]::UTF8.GetBytes($body)

Invoke-RestMethod -Uri "http://127.0.0.1:8642/v1/chat/completions" -Method POST -Headers @{ Authorization = "Bearer $apiKey" } -ContentType "application/json; charset=utf-8" -Body $utf8Body

gateway.log ist die wichtigste Quelle für API-Server-Start, Scheduled-Task-Verhalten, Provider-/Fallback-Fehler und Neustarts.

Prüfen Sie Caddy und Hermes gemeinsam, bevor Sie die endgültige Anwendung anbinden. So bleiben Anwendung, Reverse Proxy, Agent und Upstream-Modell getrennt beobachtbar.

Get-Content "C:\Users\Administrator\AppData\Local\hermes\logs\gateway.log" -Tail 100

Select-String -Path "C:\Users\Administrator\AppData\Local\hermes\logs\gateway.log" -Pattern "fallback|429|custom|gpt-oss" | Select-Object -Last 50

sc.exe query caddy
hermes gateway status

Der Hermes API Server ist OpenAI-kompatibel. Ein vorhandener OpenAI-Client benötigt daher nur Base URL, Modellalias und Bearer-Key. Codex-OAuth- und Fallback-Secrets bleiben auf dem Hermes-Server.

Lesen Sie API_SERVER_KEY aus .env und speichern Sie ihn ausschließlich serverseitig. Geben Sie ihn niemals an Browser-JavaScript aus. Wenn nur ein Applikationsserver zugreifen soll, ergänzt eine IP-Allowlist/WAF-Regel die Sicherheit.

Provider: Hermes
Typ: OpenAI-kompatible API
Base URL: https://ai-api.example.com/v1
Modell: hermes-agent
API Key: Wert von API_SERVER_KEY aus .env

POST https://ai-api.example.com/v1/chat/completions