hermes-production-ops

Hermes Production Gateway Operations

Techniques for operating a live production Hermes gateway that serves non-technical end-users via Telegram (or other messaging platforms). The core constraint: the gateway cannot go down and end-users should not see operational noise (restart pings, progress spam, error messages, technical detail).

When to Use

• Switching the global model or provider (e.g., GLM-5.2 → GLM-5.3)
• Suppressing gateway restart/startup notifications to end-users
• Tuning streaming/progress config for a messaging deployment
• Planning a gateway restart that minimizes disruption
• Any config change that requires a gateway restart to take effect

Model/Provider Switching (Global)

Workflow

1. Verify the new model exists on the provider before changing config. For Together AI, hit the models endpoint with the API key:

   curl -s "https://api.together.xyz/v1/models" \
        -H "Authorization: Bearer $TOGETHER_API_KEY" -o /tmp/models.json
   python3 -c "import json; [print(m['id']) for m in json.load(open('/tmp/models.json')) if 'glm' in m['id'].lower()]"
   

   Pitfall: Never blindly change the model string without confirming it's listed. A typo or unlisted model name will break all gateway sessions silently until rollback.

2. Edit config.yaml (at ~/.hermes/config.yaml):

   • model.default: change the model string (e.g., zai-org/GLM-5.2 → zai-org/GLM-5.3)
   • custom_providers: update the model: field in the matching provider entry
   • Both must match — model.default is what the agent uses; the custom_providers entry is the named provider definition.

3. Restart the gateway for changes to take effect:

   sudo systemctl restart hermes-gateway.service
   

   Config changes do NOT apply mid-conversation. The gateway must restart.

No-Sudo Constraint

The agent process typically runs without sudo. It cannot stop or restart hermes-gateway.service itself — the operator must do this via SSH. hermes gateway restart from inside a tool call also requires elevated privileges. This is a security feature, not a bug: recognize it after one failed attempt and hand the action to the operator instead of trying five workarounds in sequence (each failed attempt is a tool call, and under tool_progress: all each one streams a message to end-users).