type: Reference
title: Hermes gateway operations on the box
description: Per-user systemd unit, the tools/list cache trap, and the exit-75 collision.
tags: hermes, operations, gateway
status: stable
generated: crm-bot/deepseek-v4.1-flash · Fri Oct 30 2026 10:53:57 GMT+0100 (Central European Standard Time)
verified: process:live-probe · Fri Oct 30 2026 10:53:57 GMT+0100 (Central European Standard Time)

Shape

Hermes runs on the host, not in a container, as a systemd user unit with linger enabled. The API server listens on :8642 and the app reaches it through host.docker.internal.

systemctl --user is-active hermes-gateway
ss -ltn | grep 8642
journalctl --user -u hermes-gateway -n 50

The tools/list cache trap

The agent reads tools/list when it connects. A tool added to /mcp is invisible to the model until the gateway restarts — the model will insist "I don't have that tool" while the server advertises it. Check both halves:

hermes mcp test nx-master     # server side
hermes gateway restart        # then the agent

Exit 75

gateway install can restart-loop with exit 75 when an ad-hoc hermes chat gateway already owns the profile. Stop the ad-hoc one, then start the unit.

Per-profile commands

hermes profile list
hermes -p <profile> gateway status
hermes gateway list          # every profile and its status

This is the mechanism the one-bot-per-user decision relies on: a profile is an isolated instance with its own config, .env, MCP entries and API server port (API_SERVER_PORT).

Rendered from nx-master/references/gateway.md · OKF bundle · regenerate with npm run render