Windows VPS Üzerinde Hermes Agent Kurulumu: A'dan Z'ye Resimli Rehber

Bu kurulumun amacı, mevcut web uygulamasının yapay zekâ sağlayıcılarını doğrudan tek tek çağırması yerine Hermes Agent'ı merkezi bir AI gateway olarak kullanmaktır. Böylece web uygulaması yalnızca OpenAI uyumlu tek bir endpoint görür; Hermes ise ana model, fallback sağlayıcıları ve ileride açılabilecek web arama, memory ve cron yeteneklerini kendi tarafında yönetir.

Üretim mimarisinde Hermes API'sini doğrudan internete açmak yerine 127.0.0.1 üzerinde tutup Caddy ile HTTPS reverse proxy arkasına almak daha kontrollü bir yapı sağlar. Cloudflare DNS, Caddy ve Hermes birbirinden ayrı katmanlar olarak test edilebilir.

WISECP / Web Uygulaması
        ↓
https://ai-api.ornekdomain.com/v1
        ↓
Caddy :443
        ↓
127.0.0.1:8642
        ↓
Hermes Agent
        ↓
Ana model → Fallback zinciri

Hermes'in native Windows kurulumu PowerShell üzerinden çalışır. Kurulum tamamlandıktan sonra Hermes verileri varsayılan olarak Administrator profilinin LocalAppData altındaki hermes dizininde tutulur. Bu dizinde config.yaml, .env, auth.json, logs ve sessions gibi çalışma verileri yer alır.

Kurulum sihirbazında Quick Setup yerine sağlayıcı, model ve araçları kendimiz belirlemek istediğimiz için Full Setup yolunu kullandık. Ardından inference provider listesinde OpenAI sağlayıcısını seçtik.

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

hermes --version

OpenAI sağlayıcısında OpenAI Codex seçildiğinde Hermes cihaz yetkilendirme akışını başlatır. Terminalde bir device URL ve kısa süreli tek kullanımlık kod gösterilir. URL tarayıcıda açılır, kod girilir ve kullanılacak ChatGPT/Codex hesabıyla izin verilir.

Başarılı girişten sonra Hermes kendi auth durumunu saklar. Bu oturumun cihaz kodunu, auth.json içeriğini veya token değerlerini ekran görüntülerinde paylaşmayın. Cihaz kodu kısa ömürlü olsa bile güvenlik açısından secret kabul edilmelidir.

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

OAuth tamamlandığında Hermes hesabın erişebildiği modelleri listeler. Model isimleri zamanla değişebileceği için rehberdeki adı sabit bir gereksinim gibi düşünmeyin; kurulum yaptığınız anda hesabınızda görünen uygun modeli seçin.

Bu VPS'i ağırlıklı olarak WISECP ve özel web uygulamalarına metin üreten bir API gateway olarak kullandığımız için terminal, dosya yazma, code execution, browser automation ve computer use gibi yüksek yetkili araçları ilk aşamada kapattık. Böylece API anahtarına sahip bir istemcinin gereksiz şekilde VPS üzerinde işlem çalıştırma yüzeyi azaltılmış oldu.

İleride Web Search, Memory veya Cron eklerken yalnız gerçekten gereken toolset'i açmak daha güvenli bir yaklaşımdır.

hermes setup tools

hermes setup terminal

Kurulum tamamlandığında Hermes config, .env ve veri dizinlerini ekranda gösterir. OpenAI uyumlu API sunucusunu etkinleştirmek için .env dosyasına API_SERVER ayarları ekledik.

En önemli satır API_SERVER_HOST=127.0.0.1 değeridir. Bu sayede 8642 portu doğrudan internet arayüzlerine bind edilmez. Dış erişimi daha sonra Caddy üzerinden 443 portuyla sağlayacağız.

API_SERVER_KEY için örnek veya kolay tahmin edilen bir değer kullanmayın. En az 32 byte rastgele üretilmiş uzun bir secret tercih edin ve bunu yalnız sunucu ile uygulamanızın gizli ayarlarında saklayın.

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=GUCLU_RASTGELE_SECRET
API_SERVER_MODEL_NAME=hermes-agent

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

Hermes API Server, gateway süreciyle birlikte ayağa kalkar. Gateway başladıktan sonra ayrı bir PowerShell penceresinde /health endpointini test edin. Burada cevap alamıyorsanız Caddy veya Cloudflare'a geçmeden önce lokal sorunu çözün.

Sağlıklı bir kurulumda /health isteği status=ok, platform=hermes-agent ve sürüm bilgisi döndürür. Bu test, DNS ve TLS katmanlarından bağımsız olarak Hermes'in gerçekten 8642 portunda dinlediğini kanıtlar.

hermes gateway

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

Health kontrolü yalnız servisin canlı olduğunu gösterir; model tarafının gerçekten cevap verdiğini göstermez. Bu nedenle /v1/chat/completions endpointine Bearer API_SERVER_KEY ile gerçek bir istek gönderdik.

Bizim testimizde Hermes isteği OpenAI Codex'e kadar iletti fakat hesap tarafındaki kullanım sınırı nedeniyle HTTP 429 döndü. Bu sonuç bağlantının bozuk olduğu anlamına gelmez; tam tersine yerel API, kimlik doğrulama ve provider zinciri çalışmış, hata upstream model kotasında oluşmuştur.

Eski Windows PowerShell sürümlerinde bazı yeni .NET kısa metodları bulunmayabilir. RandomNumberGenerator::GetBytes(32) hatası alırsanız uyumlu byte[] yöntemiyle key üretin.

$envDosyasi = "C:\Users\Administrator\AppData\Local\hermes\.env"
$apiAnahtari = ((Get-Content $envDosyasi | 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

İlk denemede Webi üzerinden Caddy kurulumu yönetici PowerShell altında başarısız oldu. Bu durum Hermes ile ilgili değildi; Webi elevated çalışmayı desteklemediği için installer dosyayı beklenen yere taşıyamadı.

Üretim ortamında daha deterministik bir yöntem olarak resmi Caddy Windows binary paketini indirip C:\Caddy dizinine açtık. Ardından 80 ve 443 TCP portları için Windows Firewall inbound kuralları oluşturduk.

Hermes'in 8642 portu için inbound firewall kuralı oluşturmadık. 8642 yalnız localhost üzerinde kalmalıdır.

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

Caddyfile içerisinde yalnız domain ve reverse_proxy hedefi yeterlidir. Windows Not Defteri dosyayı Caddyfile.txt olarak kaydederse Caddy beklenen dosyayı bulamaz ve validate komutu hata verir.

Dosya adını gerçekten Caddyfile olacak şekilde uzantısız kaydedin veya Rename-Item ile .txt uzantısını kaldırın. Validate başarılı olduktan sonra Caddy'yi çalıştırın.

ai-api.ornekdomain.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

Domain Caddy'ye ulaşıyor fakat Hermes çalışmıyorsa dışarıdan 502 Bad Gateway görürsünüz. Caddy logunda dial tcp 127.0.0.1:8642 connection refused mesajı varsa DNS ve TLS katmanı büyük ölçüde çalışıyor, sorun reverse proxy'nin arka servise ulaşamamasıdır.

Önce curl.exe http://127.0.0.1:8642/health çalıştırın. Cevap yoksa Hermes gateway'i başlatın veya restart edin. Lokal health çalışmadan public domain testine dönmeyin.

Bu ayrım troubleshooting süresini ciddi kısaltır: Cloudflare/HTTPS hatası ile Hermes process hatasını aynı anda çözmeye çalışmayın.

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

hermes gateway

Caddy ve Hermes birlikte çalıştığında public subdomain üzerinden /health isteği Hermes cevabını döndürür. Bu aşamada zincir internet → Caddy → localhost:8642 → Hermes şeklinde tamamlanmış olur.

Cloudflare kullanıyorsanız ilk sertifika ve origin testlerini DNS only ile yapmak troubleshooting'i kolaylaştırabilir. Testler bittikten sonra proxy yeniden açılabilir ve SSL/TLS tarafında uygun doğrulama modu kullanılabilir.

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

Caddy'yi caddy.exe run ile açık bir PowerShell penceresinde bırakırsanız pencere kapandığında süreç de sona erer. Bunun yerine Caddy'yi Automatic başlangıç türünde Windows servisi olarak kaydettik.

sc.exe query caddy çıktısında STATE : 4 RUNNING görülmesi servisin arka planda çalıştığını doğrular.

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'in Windows gateway yönetimi Scheduled Task kullanabilir. Resmî akışta önce hermes gateway install ile görev kaydedilir, ardından gateway start/status komutlarıyla arka plan süreci yönetilir.

Varsayılan görev yalnız kullanıcı oturum açtığında başlıyorsa üretim VPS'inde bu yeterli değildir. Görev özelliklerinde 'Kullanıcı oturum açmışsa da açmamışsa da çalıştır' ve 'En yüksek ayrıcalıklarla çalıştır' seçeneklerini açın.

Tetikleyiciyi 'Başlatılırken / Sistem başlangıcında' olarak değiştirin. Windows görev hesabı parolasını isterse sunucunun Administrator parolasını girin; parolayı dokümana veya destek kaydına eklemeyin.

hermes gateway install

hermes gateway start
hermes gateway status

schtasks /Query /TN Hermes_Gateway /V /FO LIST

Servisleştirme tamamlandıktan sonra tüm PowerShell pencerelerini kapattık ve public health endpointinin çalışmaya devam ettiğini doğruladık. Son test ise VPS'i yeniden başlatıp RDP ile giriş yapmadan endpointi kontrol etmektir.

Bu test başarılıysa Caddy Windows servisi ve Hermes başlangıç görevi kullanıcı oturumundan bağımsız şekilde ayağa kalkıyor demektir.

Restart-Computer

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

Ana model 429, 5xx, auth veya bağlantı hatası verdiğinde Hermes'in farklı bir provider:model çiftine geçmesini sağlayabilirsiniz. Önce fallback endpointini Hermes dışında doğrudan test etmek sorunun hangi katmanda olduğunu netleştirir.

Biz OpenAI uyumlu bir LLMGate endpointi üzerinde openai/gpt-oss-20b modelini doğrudan /v1/chat/completions ile test ettik. Başarılı olduktan sonra API key'i .env içine, endpoint/model bilgisini config.yaml içindeki fallback_providers listesine ekledik.

API anahtarının kendisini config.yaml içine yazmak yerine key_env ile .env değişken adını göstermek daha temizdir. Paylaşılan ekran görüntülerinde gerçek key değerleri kullanılmamalıdır.

LLMGATE_API_KEY=GIZLI_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 bazı durumlarda JSON string'i beklenen UTF-8 encoding ile göndermeyebilir. Türkçe karakter içeren body ile Invalid JSON in request body hatası aldığımızda JSON'u UTF-8 byte dizisine çevirerek gönderdik.

UTF-8 düzeltmesinden sonra Hermes endpointi başarılı cevap verdi. Ana Codex sağlayıcısı kota nedeniyle kullanılamadığından bu test aynı zamanda fallback zincirinin cevap üretebildiğini doğruladı.

$govde = @{ model = "hermes-agent"; messages = @(@{ role = "user"; content = "VPS Hosting için kısa bir SEO açıklaması yaz." }); max_tokens = 100 } | ConvertTo-Json -Depth 5
$utf8Govde = [System.Text.Encoding]::UTF8.GetBytes($govde)

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

Hermes gateway logları başlangıç, API server bind, scheduled task ve hata akışlarını doğrulamak için önemlidir. API çağrısı çalışsa bile servis yeniden başlatma veya fallback sorunu yaşandığında ilk bakılacak yer gateway.log dosyasıdır.

Caddy ve Hermes durumlarını birlikte kontrol ettikten sonra son kullanıcı uygulamasını bağlayın. Böylece sorun çıktığında web uygulaması, Caddy, Hermes ve upstream model katmanlarından hangisinin başarısız olduğunu ayrı ayrı ölçebilirsiniz.

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

Hermes API Server OpenAI uyumlu olduğu için mevcut OpenAI-compatible istemcinizde Base URL, model ve Bearer key tanımlamak yeterlidir. Uygulama tarafının Codex OAuth tokenını veya fallback sağlayıcılarının secret değerlerini bilmesine gerek yoktur.

Üretim ortamında API_SERVER_KEY değerini .env dosyasından alın ve uygulamanızın gizli ayarına kaydedin. Makalede veya istemci tarafı JavaScript'te key yayınlamayın. Mümkünse Cloudflare/WAF üzerinde yalnız uygulama sunucunuzun IP'sine izin veren ek kural uygulayın.

Sağlayıcı: Hermes
Tip: OpenAI Uyumlu API
Base URL: https://ai-api.ornekdomain.com/v1
Model: hermes-agent
API Key: .env içindeki API_SERVER_KEY değeri

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