Gidsen

Hermes Agent installeren op Mac met Docker

18 mei 2026

Deze gids laat zien hoe je Hermes Agent op een Mac draait met Docker Desktop. Docker levert de geïsoleerde runtime, terwijl je instellingen en sessies in een vaste map op je Mac blijven staan.

Hermes Agent kan met API-sleutels werken, maar hier gebruiken we de OpenAI Codex provider met ChatGPT OAuth. De veilige volgorde is: Docker Desktop installeren, setup draaien, de provider kiezen, Hermes Agent starten en daarna het dashboard op localhost:9119 controleren.

Korte samenvatting

Installeer en start Docker Desktop voor Mac.
Gebruik het officiële image nousresearch/hermes-agent.
Mount ~/.hermes naar /opt/data zodat OAuth, configuratie, sessies, skills en logs blijven bestaan.
Draai eerst setup en kies daarna OpenAI Codex via hermes model.
Met het dashboard aan moet http://localhost:9119 in de browser openen.

Benodigdheden

Benodigdheid	Waarom
Mac	Apple Silicon en Intel Macs kunnen beide werken; kies de juiste Docker Desktop installer.
Docker Desktop	Nodig om de Hermes Agent container te draaien.
Terminal	Voor Docker-commando’s, setup, OAuth en logs.
ChatGPT-account	Nodig voor OpenAI Codex via ChatGPT OAuth.
Internetverbinding	Nodig voor het downloaden van het image en de OAuth-login.

Diagram van een Mac met Docker Desktop, een Hermes Agent container en een persistent datavolume — Docker draait Hermes Agent in een container; `~/.hermes` bewaart de data op je Mac.

Wat Docker verandert

Hermes Agent is een AI agent runtime van NousResearch. De officiële documentatie beschrijft meerdere manieren om het te gebruiken, waaronder local installation, Docker execution en Docker terminal backend. Deze gids gaat specifiek over Hermes Agent zelf draaien in een Docker-container.

Het voordeel is dat de runtime beter geïsoleerd blijft. Je hoeft Python, Node.js, browser automation dependencies en aanverwante tools niet direct op macOS te installeren. De keerzijde is dat Docker Desktop eerst moet draaien en dat bestands toegang verloopt via mappen die je expliciet mount.

Hermes Agent gebruikt /opt/data als datalocatie in de container. Daarom koppelt deze gids de Mac-map ~/.hermes aan /opt/data.

Docker Desktop installeren

Download Docker Desktop via de officiële Docker-documentatie voor Mac. Kies Apple Silicon voor M-series Macs en Intel voor oudere Intel Macs.

De installatie loopt meestal zo:

Download Docker Desktop vanaf de officiële Mac-installatiepagina.
Open Docker.dmg en verplaats Docker naar de map Programma’s.
Start Docker Desktop vanuit Programma’s.
Controleer de eerste permissie- en voorwaardenvensters.
Wacht tot het Docker-icoon stabiel klaar staat in de menubalk.

Controleer daarna:

docker --version

Als dit niet werkt, draait Docker Desktop mogelijk nog niet of is de CLI-integratie nog niet klaar.

Stroomdiagram voor Docker Desktop installatie en controle met docker version — Controleer Docker Desktop voordat je het Hermes Agent image start.

Waarom `~/.hermes` mounten

Sla deze stap niet over. Zonder volume mount kun je instellingen en authenticatie kwijtraken wanneer de container wordt verwijderd.

Gebruik dezelfde mount bij alle Hermes-commando’s:

-v ~/.hermes:/opt/data

Diagram waarin de Mac-map ~/.hermes is gekoppeld aan /opt/data in de Docker-container — De mount `~/.hermes:/opt/data` bewaart configuratie, sessies, OAuth-data, skills en logs.

Eerste keer: setup wizard starten

Maak de datamap en start de officiële setup:

mkdir -p ~/.hermes
docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent setup

Door --rm verdwijnt de tijdelijke container na afloop, maar de bestanden in /opt/data blijven in ~/.hermes.

De setup wizard kan onder meer deze bestanden en mappen aanmaken:

Locatie	Betekenis
`~/.hermes/.env`	Secrets voor API-key-providers als je die gebruikt.
`~/.hermes/config.yaml`	Model-, backend-, gateway- en toolinstellingen.
`~/.hermes/SOUL.md`	Basisgedrag en richting van de agent.
`~/.hermes/sessions/`	Sessiegeschiedenis.
`~/.hermes/memories/`	Langetermijngeheugen, als dat actief is.
`~/.hermes/skills/`	Geïnstalleerde skills.
`~/.hermes/logs/`	Runtime logs.

De exacte prompts kunnen per Hermes Agent-versie verschillen, maar dit is een veilige vuistregel:

Setup prompt	Praktische keuze
Model provider	Kies `OpenAI Codex` of een `Codex`-optie. Als die niet zichtbaar is, rond setup af en draai later `hermes model`.
Authentication method	API-key-providers bewaren waarden in `.env`. ChatGPT OAuth bewaart tokens in een auth store zoals `auth.json`.
Chat system of gateway integration	Telegram, Discord of Slack kun je later instellen als je ze niet direct gebruikt. Voor een langdurige gateway kan instellen tijdens setup handig zijn.
Onbekende defaults	Houd eerst defaults aan en pas `config.yaml` aan nadat de installatie werkt.

Laat setup dus eerst de basisbestanden maken. Als providerkeuze onduidelijk is, open je daarna opnieuw hermes model.

Controleer daarna:

ls -la ~/.hermes

Controleer ook of config.yaml bestaat. Publiceer het bestand niet volledig; lokaal de eerste regels bekijken is genoeg.

sed -n '1,80p' ~/.hermes/config.yaml

Toon of deel .env niet, omdat daar secrets in kunnen staan. Alleen bestaan controleren kan zo:

ls -la ~/.hermes/.env

Als setup klaar is maar ~/.hermes/config.yaml ontbreekt of de map leeg is, controleer dan eerst de volume mount. Het commando moet -v ~/.hermes:/opt/data bevatten.

ChatGPT OAuth instellen

Als de provider nog niet is ingesteld, open je de model picker:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent model

Kies OpenAI Codex of de dichtstbijzijnde Codex-provider. Open de URL of device code in je Mac-browser en log in met ChatGPT.

Sommige versies ondersteunen ook:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth add openai-codex --type oauth

Het OAuth-token hoort niet alleen in een wegwerpcontainer te leven. Het wordt opgeslagen in de gemounte ~/.hermes-map, bijvoorbeeld in een auth store zoals auth.json. Daardoor kun je de container opnieuw maken zonder de provider opnieuw te koppelen.

Diagram van ChatGPT OAuth in de browser verbonden met een Hermes Agent Docker-container — ChatGPT OAuth verbindt OpenAI Codex zonder een OpenAI API key in het commando te plakken.

Hermes Agent starten

Start Hermes Agent interactief:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent

Als de sessie opent, werkt de basisinstallatie. Blijf dezelfde volume mount gebruiken voor alle commando’s.

De opties betekenen:

Option	Betekenis
`docker run`	Start een nieuwe container.
`-it`	Opent een interactieve terminalsessie.
`--rm`	Verwijdert de tijdelijke container na afsluiten.
`-v ~/.hermes:/opt/data`	Koppelt de Mac-map `~/.hermes` aan `/opt/data` in de container.
`nousresearch/hermes-agent`	Gebruikt het officiële Hermes Agent Docker image.

Dashboard controleren op `localhost:9119`

Controleer na setup, providerconfiguratie en interactieve start eerst image en versie:

docker pull nousresearch/hermes-agent:latest
docker run -it --rm nousresearch/hermes-agent:latest version

Gebruik dezelfde datamap om de OAuth-status te bekijken:

docker run -it --rm \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent auth list

Voor gateway en dashboard op de achtergrond:

docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Open http://localhost:9119 of http://127.0.0.1:9119. Het dashboard is een lokale beheerinterface voor instellingen, sessies, logs en skills.

Als de pagina niet opent:

curl -I http://127.0.0.1:9119

Logs geven runtime-details:

docker logs --tail 50 hermes

Dashboardregels kunnen met [dashboard] beginnen.

Stop en verwijder de achtergrondcontainer zo:

docker stop hermes
docker rm hermes

Veelvoorkomende problemen

Probleem	Controle
`Cannot connect to the Docker daemon`	Docker Desktop draait niet.
`docker: command not found`	De Docker CLI is niet beschikbaar in Terminal.
OAuth-URL opent niet	Kopieer de URL of device code naar de Mac-browser.
OpenAI Codex provider is niet zichtbaar	Pull het nieuwste Hermes Agent image en controleer het menu `hermes model` opnieuw.
Instellingen verdwijnen	De mount `-v ~/.hermes:/opt/data` ontbreekt of wijkt af.
Permission error	Controleer of de huidige macOS-gebruiker naar `~/.hermes` mag schrijven.
Dashboard opent niet	Controleer `-p 9119:9119`, `-e HERMES_DASHBOARD=1` en `[dashboard]` logs.
Poortconflict	Een ander proces gebruikt `8642` of `9119`.

Op Apple Silicon Macs handelt Docker Desktop architectuurverschillen meestal af, zolang je geen Intel-only image forceert. Begin met het officiële latest image en een actuele Docker Desktop-installatie.

Flow voor Docker-status, OAuth, volume mount, logs en dashboard — Controleer Docker, OAuth, volume mount, logs en daarna de dashboardpoort.

Updaten of verwijderen

Update door het nieuwste image te trekken en de container opnieuw te maken:

docker pull nousresearch/hermes-agent:latest
docker rm -f hermes
docker run -d \
  --name hermes \
  --restart unless-stopped \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  -p 9119:9119 \
  -e HERMES_DASHBOARD=1 \
  nousresearch/hermes-agent gateway run

Verwijderen:

docker rm -f hermes
docker rmi nousresearch/hermes-agent:latest

Verwijder ~/.hermes alleen als je ook instellingen, OAuth-tokens, sessies, skills en logs wilt wissen.

rm -rf ~/.hermes

Kernpunten

De stabiele volgorde is Docker Desktop installeren, setup draaien, OpenAI Codex via ChatGPT OAuth verbinden, ~/.hermes naar /opt/data mounten en in gateway-modus http://localhost:9119 controleren.