Hermes Agent: handleiding voor zelfgehoste installatie voor thuisservergebruikers

Eva Wong is de technisch schrijver en vaste knutselaar bij ZimaSpace. Als levenslange geek met een passie voor homelabs en open-sourcesoftwareis ze gespecialiseerd in het vertalen van complexe technische concepten naar toegankelijke, praktische handleidingen. Eva vindt dat self-hosting leuk moet zijn en niet intimiderend. Met haar tutorials helpt ze de community om hardware-installaties te doorgronden, van het bouwen van hun eerste NAS tot het beheersen van Docker-containers.

Kort antwoord

Hermes Agent kan op een thuisserver zelf worden gehost als je een AI-agent wilt die verbinding kan maken met een modelprovider, tools kan gebruiken en kan communiceren via een berichten-gateway zoals Telegram. Voor de meeste beginners is het niet alleen lastig om de app te laten draaien. Het is ook belangrijk te begrijpen waar elke handeling plaatsvindt: op de hostserver, in de container, in de app-omgeving of via een berichtenplatform.

Een veilige zelfgehoste installatie moet antwoord geven op zes vragen voordat je problemen gaat oplossen:

  • Werk ik op de host of in de container?
  • Waar staan de app-configuratie, logs, downloads en runtimegegevens?
  • Welke gebruiker is eigenaar van de bestanden en voert de app uit?
  • Kan de app de modelprovider en de berichten-API bereiken?
  • Zijn API-sleutels, bottokens en toegestane lijsten beschermd?
  • Hoe controleer ik of de agent na een herstart nog werkt?

Als je deze grenzen duidelijk houdt, wordt het veel eenvoudiger om de installatie van Hermes Agent te begrijpen, te controleren en problemen op te lossen.

Wat is Hermes Agent in een zelfgehoste thuisserveropstelling?

Hermes Agent is een zelfgehoste AI-agentworkflow die verbinding kan maken met een modelprovider, tools kan gebruiken en kan communiceren via de terminal of berichtenkanalen. Op een thuisserver bevindt deze zich vaak tussen je AI-model, je serveromgeving en een communicatie-interface, zoals een webdashboard of botgateway.

Het belangrijkste is dat een zelfgehoste agent niet zomaar een chatbot is. Afhankelijk van de configuratie kan deze communiceren met bestanden, terminaltools, model-API's, berichtenplatforms en runtimegegevens. Daarom zijn grenzen voor paden, rechten en toegang belangrijk.

Wat Hermes Agent doet voor AI-interactie en berichtenverkeer

Hermes Agent kan worden geconfigureerd om verbinding te maken met een modelprovider, gesprekken te starten, tools te gebruiken en verbinding te maken met berichtengateways. De snelstartgids voor Hermes Agent legt uit hoe gebruikers Hermes kunnen installeren, een modelprovider kunnen configureren, een eerste gesprek kunnen starten, terminaltools kunnen gebruiken en later berichtenplatforms kunnen koppelen via een gateway.

Voor een thuisservergebruiker betekent dit dat Hermes een permanente AI-assistent kan worden die draait op een apparaat dat je zelf beheert. Er kunnen ook nieuwe installatielagen bijkomen: modelgegevens, de runtime van de app, gatewayinstellingen en toegangsrechten.

Wanneer een WebUI-installatie voldoende is

Een WebUI-installatie is meestal voldoende als de app alle benodigde instellingen rechtstreeks in het dashboard aanbiedt. Dit is voor de meeste gebruikers de veiligste aanpak, omdat je zo niet de containerterminal hoeft te gebruiken, tenzij er iets ontbreekt of niet werkt.

Een aanpak waarbij de WebUI centraal staat, is geschikt wanneer:

  • de app probleemloos wordt geรฏnstalleerd;
  • de modelprovider via de interface kan worden geconfigureerd;
  • de berichten-gateway verbinding kan maken zonder toegang tot de shell;
  • het dashboard de status duidelijk weergeeft;
  • de logboeken geen toestemmings- of netwerkfouten bevatten.

Als het dashboard de optie biedt die je nodig hebt, gebruik die dan eerst. Het configureren van de containerterminal moet worden beschouwd als een terugvaloptie of geavanceerde methode, en niet als de standaard eerste stap voor iedere gebruiker.

Wanneer je de containerterminal moet configureren

Mogelijk moet je de containerterminal configureren als het dashboard geen optie biedt die je nodig hebt, als de app een installatiewizard in de container vereist, of als je voor het oplossen van problemen toegang nodig hebt tot logboeken, de runtime-omgeving of app-specifieke opdrachten.

Hier raken veel gebruikers in de war. Een opdracht die in de shell van de host wordt uitgevoerd, heeft mogelijk geen effect op de app in de container. Een bestand dat zichtbaar is in de container, bestaat mogelijk niet op hetzelfde pad op de host. Een toestemmingsfout kan worden veroorzaakt door de gebruiker waaronder de app draait, en niet door de modelprovider of het bottoken.

Controleer voordat je de containerterminal gebruikt precies in welke shell je zit en als welke gebruiker je bent aangemeld.

Wat je nodig hebt voordat je begint

Voor een zelfgehoste agentinstallatie is meer nodig dan een actieve server. Je hebt een werkende netwerkverbinding, toegang tot een model, inloggegevens voor berichten en voldoende rechten nodig om de app te beheren zonder per ongeluk de verkeerde bestanden te wijzigen.

Een homeserver met internettoegang

De homeserver moet toegang hebben tot internet als je een cloudmodelprovider of berichten-API wilt gebruiken. Als je een lokaal modeleindpunt gebruikt, moet de server dat eindpunt nog steeds kunnen bereiken via het lokale netwerk of containernetwerk.

Netwerktoegang is belangrijk, omdat een agent correct geรฏnstalleerd kan lijken en toch niet reageert. De verbinding met de modelprovider, de berichtengateway en het dashboard kunnen bijvoorbeeld elk afhankelijk zijn van een ander netwerkpad.

Controleer eerst het volgende:

  • de server een stabiele LAN-verbinding heeft;
  • de server toegang heeft tot het modeleindpunt of de modelprovider;
  • de server toegang heeft tot de berichten-API;
  • de dashboardpoort bereikbaar is vanuit je browser;
  • er geen firewallregel is die de gateway blokkeert.

Een modelprovider of lokaal modeleindpunt

Hermes heeft een modelverbinding nodig om bruikbare antwoorden te kunnen geven. Dit kan een cloudprovider, een API-sleutel of een OpenAI-compatibel eindpunt zijn. Sommige gebruikers kunnen een lokale modelservice verbinden als hun hardware en modelstack dit ondersteunen.

Het belangrijkste bij de installatie is dat de modelconfiguratie losstaat van de configuratie van het berichtenplatform. Een bot kan correct zijn verbonden terwijl de modelprovider verkeerd is ingesteld, en een modelprovider kan werken terwijl de botgateway niet werkt.

Zorg dat je de basis-URL van het model, de API-sleutel, de modelnaam en de contextinstellingen bij de hand hebt voordat je met de installatie begint.

Een account voor een berichtenplatform en een bottoken

Als je via Telegram of een ander berichtenplatform met de agent wilt praten, heb je een account voor dat berichtenplatform en inloggegevens voor een bot of gateway nodig. Voor Telegram betekent dit meestal dat je een bot maakt en het token ervan opslaat.

Behandel een bot-token als een wachtwoord. Telegram legt uit dat elke bot een uniek token krijgt om verzoeken aan de Bot API te autoriseren. Verzoeken bevatten het token in het API-pad volgens het autorisatiemodel voor Telegram-bot-tokens.

Plak een bot-token niet in openbare chats, schermafbeeldingen, logboeken, GitHub-issues of gedeelde documenten. Als een token wordt blootgesteld, genereer dan een nieuw token via de officiรซle procedure van het berichtenplatform.

IP-adres van de host, inlogtoegang en containermachtigingen

U hebt het IP-adres van de host nodig om het serverdashboard te openen of via SSH verbinding te maken. U hebt ook toegang tot een account nodig waarmee u de app veilig kunt beheren.

Bij installaties op basis van containers zijn machtigingen vaak gelaagd:

Machtigingslaag Wat het beheert Veelgemaakte fout Veilige controle
Hostgebruiker / SSH-account Toegang tot het bestandssysteem van de homeserver, Docker-opdrachten en het serverdashboard. Aannemen dat hostmachtigingen automatisch ook in de container gelden. Controleer met welk account u bent aangemeld en welke acties op serverniveau dit account kan uitvoeren.
Containergebruiker De gebruiker die het app-proces uitvoert en app-bestanden schrijft in de container. De installatie uitvoeren als root terwijl de app normaal gesproken met een niet-rootgebruiker wordt uitgevoerd. Controleer welke containergebruiker u nodig hebt voordat u app-gegevens aanmaakt of bewerkt.
Gekoppelde hostmap De hostmap of het Docker-volume dat beschikbaar wordt gemaakt in de container. Een hostmap bewerken die niet is gekoppeld aan het pad dat de app uitleest. Controleer het bronpad op de host en het bestemmingspad in de container.
App-runtimepad Waar de configuratie, logboeken, downloads, sessies en tijdelijke gegevens worden opgeslagen. Bestanden in de verkeerde laag wijzigen of instellingen verliezen na een herstart. Controleer of het pad na een herstart behouden blijft en beschrijfbaar is voor de app-gebruiker.

Ga er niet van uit dat root altijd de juiste keuze is. Als u op het verkeerde moment root gebruikt, kunnen bestanden ontstaan die eigendom zijn van root en die de app-gebruiker later niet kan aanpassen.

Hostpad vs. containerpad vs. pad van app-gegevens

Dit is het belangrijkste concept in dit artikel. Veel problemen met de installatie van Hermes Agent ontstaan doordat hostpaden, containerpaden, app-gegevenspaden, logboeken, downloads en gekoppelde volumes door elkaar worden gehaald.

Gebruik De Agent-containerbeheerkaart voordat u opdrachten uitvoert of problemen ermee opspoort.

Laag Te beantwoorden vraag Validatiesignaal Veelvoorkomende fout
Hostsystemen Zijn de server, het dashboard, de SSH-sessie en de containerbeheerder bereikbaar? Het dashboard of de SSH-sessie wordt geopend en de container is zichtbaar als actief. De app lijkt geรฏnstalleerd, maar de server of container is niet daadwerkelijk bereikbaar.
Container-runtime Bevindt u zich in de juiste container en gebruikt u de verwachte gebruiker? De shell, werkmap en gebruiker komen overeen met het app-installatiepad. Opdrachten worden uitgevoerd in de shell van de host en hebben geen invloed op de app in de container.
Pad van app-gegevens Waar staan de configuratie, logboeken, downloads en runtimebestanden? Instellingen en logboeken blijven bewaard na een herstart en zijn beschrijfbaar voor de app-gebruiker. Instellingen verdwijnen na een herstart of de app geeft foutmeldingen over geweigerde toegang.
Netwerkpad Kan de container de modelprovider, het lokale eindpunt en de berichten-API bereiken? Providercontroles, gatewayaanroepen en dashboardtoegang werken vanuit de verwachte laag. Het model of de bot werkt niet, hoewel de app correct geรฏnstalleerd lijkt.
Referenties en toegang Zijn API-sleutels, bot-tokens en toegestane gebruikers veilig ingesteld? Privรฉtestberichten werken en de logboeken bevatten geen token- of toegangsproblemen. Het bot-token is ongeldig, is blootgesteld of de toegestane gebruikers-ID is onjuist.
Validatie na herstart Werkt de installatie nog steeds na een herstart van de gateway of service? De bot reageert, het dashboard werkt goed en de logboeken blijven na een herstart schoon. De oude configuratie blijft actief of nieuwe instellingen worden niet opgeslagen.

Wat het hostsysteem kan zien

Het hostsysteem is het daadwerkelijke besturingssysteem van de homeserver. Het kan hostmappen, Docker-containers, netwerkinterfaces, opslagapparaten en services op systeemniveau zien.

Als een app in Docker draait, ziet de host het interne pad van de app mogelijk niet op dezelfde manier als de container. De host ziet mogelijk een Docker-volume, een gekoppelde map of containermetadata.

Daarom betekent een pad zoals /opt/data of /app/config mogelijk niet hetzelfde op de host als in de container.

Wat de container kan zien

Een container ziet zijn eigen bestandssysteem. Mogelijk ziet hij ook hostmappen die in de container zijn gekoppeld. Het containerpad is het pad vanuit het perspectief van de app.

Docker legt uit dat een bind-mount een bestand of map van de hostmachine in een container koppelt, terwijl een Docker-volume wordt aangemaakt in de opslagmap van Docker op de host en door Docker wordt beheerd via het opslagmodel voor Docker-bind-mounts.

Dat onderscheid is belangrijk, omdat een container alleen toegang heeft tot de hostpaden die erin zijn gekoppeld. Als de app een bestand niet kan vinden, bestaat het bestand mogelijk wel op de host, maar is het niet gekoppeld aan het verwachte containerpad.

Waar appconfiguratie en runtimegegevens gewoonlijk staan

App-configuratie, logboeken, downloads en runtimegegevens kunnen op verschillende locaties staan, afhankelijk van hoe de app is verpakt. Sommige gegevens staan mogelijk in de container, andere op een Docker-volume en weer andere zijn als bind-mount gekoppeld vanaf de host.

Veelvoorkomende gegevenstypen voor een zelfgehoste agent zijn:

  • instellingen van de modelprovider;
  • gatewayconfiguratie;
  • bot-token- of berichtinstellingen;
  • logboeken en sessiestatus;
  • tijdelijke downloads;
  • tooluitvoer;
  • app-specifieke runtimegegevens.

De belangrijke vraag is niet alleen โ€žwaar staat het bestand?โ€, maar ook โ€žwelke laag beheert dit bestand en welke gebruiker kan het aanpassen?โ€

Hermes Agent-scherm voor het selecteren van een modelprovider tijdens de installatie

Waarom verwarring over paden problemen met machtigingen en gegevens veroorzaakt

Verwarring over paden veroorzaakt twee veelvoorkomende problemen. Ten eerste bewerken gebruikers een bestand op de host, terwijl de container een ander bestand op een eigen pad leest. Ten tweede voeren gebruikers de installatie uit als root en maken ze bestanden aan die de app-gebruiker later niet kan wijzigen.

Bind mounts kunnen ook bestaande containerbestanden verbergen als er een hostmap wordt gekoppeld aan een niet-lege containermap. In dat geval lijken bestanden misschien te ontbreken, terwijl ze alleen door de koppeling aan het zicht zijn onttrokken.

Controleer voordat je een probleem met appgegevens oplost de runtime-laag, de gekoppelde paden, de bestandseigenaar en de containergebruiker.

Een zelfgehoste agent stap voor stap configureren

Bij de installatie van een zelfgehoste agent begin je met controles met een laag risico, ga je daarna verder met de configuratie en sluit je af met validatie. Wijzig geen machtigingen en start geen services opnieuw voordat je weet welke laag problemen veroorzaakt.

Stap 1: Installeer of open de app via het dashboard van je server

Begin met de eenvoudigste ondersteunde installatiemethode of manier om de app op je homeserver te starten. Als de server een appdashboard heeft, gebruik dit dan om te controleren of Hermes Agent is geรฏnstalleerd, zichtbaar is en actief is.

Open in deze fase de container niet, tenzij de app dit vereist. Controleer eerst de status van het dashboard, de app-versie als die wordt weergegeven en of er een configuratiepagina beschikbaar is.

Als de app helemaal niet kan starten, controleer dan de logboeken voordat je configuratiebestanden wijzigt.

Stap 2: Controleer het IP-adres van de host en de netwerktoegang

Controleer het IP-adres van de host en zorg dat je browser of terminal de server kan bereiken. Afhankelijk van de configuratie kan hetzelfde IP-adres worden gebruikt voor toegang tot het dashboard, SSH-toegang of toegang tot de lokale gateway.

Controleer vervolgens de uitgaande netwerktoegang. Een berichtenbot reageert niet als de container geen verbinding kan maken met de berichten-API, en een modelprovider werkt niet als de server geen verbinding kan maken met het modelendpoint.

Met deze controle kun je onderscheid maken tussen โ€˜app-configuratie misluktโ€™ en โ€˜netwerktoegang misluktโ€™.

Stap 3: Open de container met de juiste gebruiker

Als de terminal van de container moet worden ingesteld, open je de container met de gebruiker die de app verwacht. Dit is belangrijk, omdat bestanden die door de verkeerde gebruiker zijn aangemaakt later problemen met machtigingen kunnen veroorzaken.

Behandel de shell van de host en die van de container niet als dezelfde omgeving. Een opdracht die op de host werkt, bestaat mogelijk niet in de container, en een bestandspad in de container bestaat mogelijk niet op de host.

Controleer het volgende voordat je installatieopdrachten uitvoert:

  1. Je bevindt je in de juiste container.
  2. Je gebruikt de beoogde containergebruiker.
  3. Je bevindt je in de verwachte werkmap.
  4. De vereiste app-opdracht is beschikbaar.
  5. Je weet hoe je de container kunt verlaten en opnieuw openen.

Stap 4: Activeer de app-omgeving voordat je installatieopdrachten uitvoert

Sommige zelfgehoste apps gebruiken een virtuele omgeving of een app-specifieke shellconfiguratie. Als de omgeving niet is geactiveerd, wordt de app-opdracht mogelijk niet gevonden of wordt deze uitgevoerd met de verkeerde afhankelijkheden.

Deze stap is niet zomaar een formaliteit. Zo weet je zeker dat de installatiewizard, de gatewayopdracht en de opdracht voor de modelconfiguratie in dezelfde runtimecontext als de app worden uitgevoerd.

Als een opdracht onverwacht mislukt, controleer dan of je in de juiste container zit en of de app-omgeving actief is voordat je iets opnieuw installeert.

Stap 5: verbind een modelprovider of lokale modelservice

Configureer de modelprovider, het aangepaste eindpunt of de lokale modelservice. Zorg dat de basis-URL, API-sleutel, modelnaam en contextinstellingen overeenkomen met de provider die je gebruikt.

Controleer bij problemen met de modelconfiguratie het volgende in deze volgorde:

  • Klopt de API-sleutel?
  • Is de basis-URL bereikbaar vanuit de container?
  • Wordt de modelnaam door het eindpunt ondersteund?
  • Heeft de app een model met een lange context nodig?
  • Zijn er netwerk- of DNS-problemen in de container?

Houd modelfouten en berichtenfouten gescheiden. Dat een Telegram-bot niet reageert en een modelprovider uitvalt, houdt alleen verband met elkaar doordat de agent beide nodig heeft om de workflow te voltooien.

Stap 6: configureer de berichten-gateway

De berichten-gateway verbindt de runtime van de agent met een berichtenplatform. Voor Telegram gaat het doorgaans om een bottoken en de identiteit van toegestane gebruikers.

Een goede gatewayconfiguratie bepaalt wie de agent berichten mag sturen, welk bottoken wordt gebruikt en of de bot bedoeld is voor privรฉchats, groepschats of beide.

Behandel een berichtenbot nooit standaard als een openbare interface. Een zelfgehoste agent kan toegang hebben tot tools, lokale gegevens of acties die niet beschikbaar mogen zijn voor elke gebruiker die de bot kan bereiken.

Stap 7: start de gateway opnieuw en pas de nieuwe configuratie toe

Na wijzigingen aan het model of de berichten-gateway moet de gateway mogelijk opnieuw worden gestart voordat de nieuwe configuratie wordt toegepast. Het gedrag na een herstart is belangrijk, omdat een installatie voltooid kan lijken terwijl er nog oude instellingen actief zijn.

Controleer na de herstart zowel aan de gebruikerskant als aan de serverkant of alles werkt. Stuur een testbericht, controleer de dashboardstatus en bekijk de logboeken op machtigings-, token- of netwerkfouten.

Als de herconfiguratie na een herstart niet behouden blijft, controleer dan opnieuw het gegevenspad en de machtigingsgrenzen.

Bedieningsscherm van de Hermes Agent Telegram-bot voor het valideren van de berichten-gateway

Machtigingen, tokens en toegangsbeheer

Zelfgehoste agents combineren lokale runtime-machtigingen met externe inloggegevens. Daardoor kan een installatie technisch werken, maar toch onveilig zijn als tokens, toegestane lijsten of gebruikersgrenzen niet goed zijn ingesteld.

Waarom de containergebruiker belangrijk is

De containergebruiker bepaalt welke bestanden de app in de container kan lezen en schrijven. Als installatieopdrachten als root worden uitgevoerd en de app later als niet-rootgebruiker draait, kan de app geen toegang meer hebben tot de appgegevens.

Dit verschijnt vaak als een machtigingsfout in het gegevenspad van de app. De oplossing is niet altijd om root te blijven gebruiken. In veel gevallen kun je het beter oplossen door het eigendom te herstellen en de app als de bedoelde gebruiker uit te voeren.

Gebruik root alleen wanneer dat nodig is voor een specifieke herstelstap en maak gewone app-bestanden niet aan als root.

Waarom API-sleutels en bot-tokens beveiligd moeten zijn

API-sleutels en bot-tokens zijn inloggegevens. Een API-sleutel voor een model kan toegang geven tot een modelprovider. Met een bot-token kunnen verzoeken namens de bot worden gedaan.

Zet deze waarden niet in openbare repositories, schermafbeeldingen, gedeelde logboeken of supportberichten. Maak tokens onleesbaar voordat je configuratie of logboeken deelt tijdens het oplossen van problemen.

Als een token is blootgesteld, vervang het dan in plaats van te hopen dat niemand het gebruikt.

Hoe een lijst met toegestane gebruikers de privรฉtoegang regelt

Een lijst met toegestane gebruikers beperkt welke gebruikers via een berichten-gateway met de agent kunnen communiceren. Dit is belangrijk omdat een berichtenbot mogelijk voor meer mensen bereikbaar is dan je verwacht.

Gebruik voor privรฉ-AI-chats de kleinst mogelijke lijst met toegestane gebruikers. Controleer of de toegestane gebruikers-ID klopt en of testberichten van dat account komen.

Als meerdere mensen toegang nodig hebben, voeg ze dan bewust toe in plaats van de bot voor iedereen toegankelijk te laten.

Waarom berichtenbots niet als openbare interfaces moeten worden behandeld

Een berichtenbot kan aanvoelen als een gewone chatinterface, maar erachter kan een zelfgehoste agent zitten met toegang tot modellen, tools, sessies en lokale runtime-machtigingen.

Daardoor is het iets anders dan een eenvoudige meldingenbot. De bot moet duidelijke toegangsregels hebben, tokens moeten beveiligd zijn en het netwerkpad moet gecontroleerd zijn.

Wees voorzichtig met groepschats. Groepsmachtigingen, de privacymodus en de beheerdersstatus van de bot kunnen bepalen welke berichten de bot kan zien of beantwoorden.

Veelvoorkomende installatieproblemen en hoe je ze oplost

De meeste installatieproblemen zijn terug te voeren op een van de zes lagen: runtime, gegevenspad, machtigingen, gateway, geheim of validatie.

Machtigingsfouten in het pad naar app-gegevens

Een machtigingsfout betekent meestal dat de huidige app-gebruiker een vereist bestand of een vereiste map niet kan lezen of beschrijven. Dit kan gebeuren als bij een eerdere installatieopdracht bestanden als root zijn aangemaakt of als een gekoppelde map de verkeerde eigenaar heeft.

Controleer eerst het volgende:

  • Werk je in de container of op de host?
  • Welke gebruiker voert de app uit?
  • Wie is de eigenaar van de map met app-gegevens?
  • Is het pad naar de app-gegevens gekoppeld vanaf de host?
  • Is er eerder een installatieopdracht uitgevoerd als root?

Wijzig niet recursief de machtigingen van grote mappen, tenzij je weet wat het doel is. Los het probleem op voor alleen het kleinste specifieke pad dat nodig is.

Bot reageert niet na de installatie

Een bot kan soms niet reageren, zelfs als Hermes Agent zelf actief is. Het probleem kan te maken hebben met het token, de lijst met toegestane gebruikers, de berichten-gateway, netwerktoegang of groepsmachtigingen.

Controleer dit in deze volgorde:

  1. Controleer of het bot-token klopt.
  2. Controleer of de gebruikers-ID is toegestaan.
  3. Controleer of de gateway na de configuratie opnieuw is gestart.
  4. Controleer of de container de berichten-API kan bereiken.
  5. Controleer de app-logboeken op token-, netwerk- of machtigingsfouten.
  6. Test de privรฉchat voordat je problemen met groepschats oplost.

Een privรฉchat testen is meestal eenvoudiger dan een groepschat testen, omdat groepsmachtigingen extra variabelen toevoegen.

De instellingen van de modelprovider zijn onjuist

Als de berichtenbot reageert maar antwoorden van het model uitblijven, ligt het probleem mogelijk bij de modelprovider. Controleer de basis-URL, API-sleutel, modelnaam en compatibiliteit van het endpoint.

Controleer bij lokale modelendpoints ook of de modelservice actief en bereikbaar is vanuit de container. Een service die vanaf de host bereikbaar is, is mogelijk niet bereikbaar vanuit de container als de netwerkinstellingen verschillen.

Houd het oplossen van problemen met de provider gescheiden van het oplossen van problemen met berichtenverkeer. Zo voorkom je dat je de bot aanpast terwijl het probleem in werkelijkheid bij de modelverbinding ligt.

De container kan geen verbinding maken met de berichten-API

Als de container geen verbinding kan maken met de berichten-API, kan de gateway niet op de juiste manier berichten ontvangen of versturen. Dit kan komen door DNS-problemen, firewallregels, proxyinstellingen of ontbrekende uitgaande internettoegang.

Controleer of de host internettoegang heeft en of de container internettoegang heeft. Dat is niet altijd hetzelfde.

Als de homeserver een VPN, proxy of beperkt netwerk gebruikt, controleer dan of de container uitgaande HTTPS-verzoeken mag doen.

Groepschatmachtigingen of de privacymodus blokkeren reacties

Groepschats werken ingewikkelder dan privรฉchats. Een bot kan wel reageren in een privรฉchat maar niet in een groep, omdat de bot het bericht niet kan zien, niet de juiste machtiging heeft of wordt beperkt door privacyinstellingen.

Begin met testen in een privรฉchat. Test daarna de groepschat afzonderlijk.

Controleer bij gebruik in een groep of je de bot rechtstreeks moet vermelden, of de bot beheerdersmachtigingen nodig heeft en of de privacyinstellingen toestaan dat de bot de benodigde berichten ontvangt.

Controleren of Hermes Agent werkt

De installatie is niet voltooid zodra de installatie zelf klaar is. Ze is pas voltooid als het model, de gateway, de machtigingen, het dashboard, de logboeken en de werking van de herconfiguratie allemaal de basistests doorstaan.

De installatiewizard wordt zonder fouten voltooid

De installatiewizard moet worden voltooid zonder fouten over ontbrekende opdrachten, providerfouten of machtigingsfouten. Als de wizard mislukt, noteer dan welke laag de fout veroorzaakte voordat je het opnieuw probeert.

Een fout in de installatiewizard valt meestal in een van deze categorieรซn:

  • inloggegevens van de modelprovider;
  • runtimeomgeving;
  • containermachtigingen;
  • ontbrekende app-opdracht;
  • netwerktoegang;
  • gatewayconfiguratie.

Gebruik die categorie om te bepalen wat je vervolgens moet controleren.

De berichtenbot reageert op een privรฉtestbericht

De eenvoudigste manier om berichtenverkeer te testen is met een privรฉtestbericht. Stuur een standaardbericht en controleer of de bot reageert.

Als een privรฉchat werkt, zijn het token, de allowlist, de gateway en de modelverbinding waarschijnlijk grotendeels correct ingesteld. Als de groepschat nog steeds niet werkt, richt je dan op groepsmachtigingen en privacy-instellingen in plaats van de app opnieuw te installeren.

Een privรฉchat moet je eerste geslaagde berichtentest zijn.

Het dashboard toont dat de agent actief is

Afhankelijk van het systeem moet het dashboard aangeven dat de agent of gateway actief is. De dashboardstatus is nuttig omdat die een serverweergave biedt, in plaats van dat je alleen op de berichtenapp hoeft te vertrouwen.

Als het dashboard een gestopte of ongezonde status toont, controleer dan de logs voordat je tokens of modelinstellingen wijzigt.

De dashboardstatus en de botreactie moeten overeenkomen. Als het ene werkt en het andere niet, wijst die discrepantie naar de laag waar het probleem zit.

Geen fouten met machtigingen of netwerkproblemen in de logs

In de logs mogen niet herhaaldelijk fouten verschijnen zoals โ€˜toegang geweigerdโ€™, โ€˜ongeldig tokenโ€™, โ€˜provider niet bereikbaarโ€™, โ€˜gateway misluktโ€™ of โ€˜netwerktime-outโ€™.

Gebruik logs om de volgende stap te bepalen. Een fout met machtigingen wijst op bestandseigendom of de containergebruiker. Een netwerkfout wijst op de bereikbaarheid van de API. Een tokenfout wijst op de configuratie van inloggegevens.

Probeer niet alle lagen tegelijk te herstellen. Wijzig รฉรฉn variabele, start indien nodig opnieuw op en test opnieuw.

Herconfiguratie werkt na een herstart

Een duurzame configuratie moet een herstart of herconfiguratie doorstaan. Start na het wijzigen van model- of gatewayinstellingen de vereiste service of gateway opnieuw op en controleer of de nieuwe instellingen nog steeds van toepassing zijn.

Als instellingen na een herstart verdwijnen, controleer dan waar de configuratie is opgeslagen en of het app-datapad persistent is.

Hier wordt kennis van hostpaden, containerpaden en gekoppelde volumes praktisch.

Zo werkt dit in een echte thuisserveromgeving

In een echte thuisserveromgeving blijft het algemene installatiemodel hetzelfde: controleer de runtime-laag, controleer de datapaden, beveilig inloggegevens, configureer gatewaytoegang en valideer met logs en de dashboardstatus.

Een apparaatspecifieke installatiegids kan vervolgens het exacte commandopad bieden. Zo legt de ZimaOS-configuratieprocedure voor Hermes Agent een installatieroute voor Hermes Agent uit met configuratie van de modelprovider, koppeling van een Telegram-bot, toegang tot de Hermes-container als app-gebruiker, activering van de app-omgeving, uitvoering van installatiecommandoโ€™s, controle van de dashboardstatus en oplossing van problemen met machtigingen of botreacties.

Voor gebruikers die zelf gehoste apps, berichtengateways en lichte agentworkflows draaien op een compacte server die altijd aanstaat, past de ZimaBoard 2-thuis-AI-server bij het soort omgeving waarin Docker-apps, terminaltoegang, lokale services en app-specifieke datapaden samen moeten worden begrepen. Het is niet de enige manier om een agent te hosten, maar wel een relevant voorbeeld van het soort thuisserverworkflow dat in dit artikel wordt beschreven.

De belangrijkste les is overal toepasbaar: onthoud niet alleen รฉรฉn configuratieopdracht uit je hoofd. Begrijp op welke laag je werkt en hoe je het resultaat controleert.

Veelgestelde vragen

Kan ik Hermes Agent alleen via een webdashboard configureren?

In veel gevallen volstaat een webdashboard voor de basisconfiguratie, vooral als het instellingen voor modellen en de gateway biedt. Configuratie via de containerterminal is nodig wanneer het dashboard geen benodigde optie biedt of wanneer je voor probleemoplossing opdrachten op app-niveau nodig hebt. Begin indien mogelijk met de WebUI en gebruik de containerterminal alleen als de configuratie dat vereist.

Waarom moet ik de container openen in plaats van de shell van de host te gebruiken?

Sommige app-opdrachten zijn alleen beschikbaar in de container, omdat daar de app-runtime en afhankelijkheden staan. Dezelfde opdracht uitvoeren op de host kan mislukken of de verkeerde omgeving beรฏnvloeden. Als je de container met de juiste gebruiker opent, weet je zeker dat configuratiewijzigingen op de app zelf van toepassing zijn.

Wat is het verschil tussen hostgegevens en app-gegevens van containers?

Hostgegevens staan op het bestandssysteem van de homeserver. App-gegevens van containers kunnen in de container zelf staan, in een door Docker beheerd volume of in een hostmap die aan de container is gekoppeld. Hetzelfde zichtbare mappad betekent niet per se hetzelfde tussen de host- en containerlagen, dus controleer de koppelingen en de locaties van app-gegevens voordat je bestanden bewerkt.

Waarom geeft Hermes Agent een machtigingsfout weer?

Een machtigingsfout betekent vaak dat de app-gebruiker een vereist bestand of een vereiste map niet kan lezen of beschrijven. Dit kan gebeuren als bestanden door root zijn aangemaakt, als een gekoppelde map de verkeerde eigenaar heeft of als de container onder een andere gebruiker draait dan verwacht. Controleer de runtime-laag, de containergebruiker, het app-gegevenspad en het eigendom van bestanden voordat je brede machtigingen wijzigt.

Waarom reageert mijn Telegram-bot niet?

Een Telegram-bot reageert mogelijk niet omdat het token onjuist is, de gebruikers-ID niet is toegestaan, de gateway niet opnieuw is gestart, de container geen verbinding kan maken met de Telegram-API of de machtigingen voor groepschats het bericht blokkeren. Test eerst een privรฉchat, omdat daarmee veel variabelen rond groepen wegvallen. Controleer daarna de logboeken op fouten met het token, netwerk- of machtigingsproblemen.

Moet ik Hermes Agent rechtstreeks toegankelijk maken via internet?

Directe openbare toegang is doorgaans niet de beste standaardkeuze voor een zelfgehoste agent. Een berichtenbot of gateway kan verbinding maken met tools, toegang tot modellen en mogelijk lokale runtime-acties, dus moet de toegang worden beperkt. Gebruik privรฉtoegang, sterke inloggegevens, toelatingslijsten en terughoudende machtigingen voordat je een openbare opstelling overweegt.

Ondersteuning en tips

Meer om te lezen

Get More Builds Like This

Stay in the Loop

Get updates from Zima - new products, exclusive deals, and real builds from the community.

Stay in the Loop preferences

We respect your inbox. Unsubscribe anytime.