Gateway Internals and Message Routing

The Hermes gateway is a long-running router between external messaging platforms and the shared agent core. It normalizes inbound events, authorizes the sender, resolves a session, runs the agent, and hands the result to the correct adapter for delivery.

Official documentation: https://hermes-agent.nousresearch.com/docs/developer-guide/gateway-internals

Inbound to outbound

A platform adapter converts a native event into a common message event. The gateway checks allowlists or pairing, builds a platform-aware session key, handles bypass commands, and creates or resumes the appropriate agent. Replies pass through the delivery layer rather than being written directly by the agent core.

Active sessions have special steering and interruption behavior. Commands such as stop, approve, deny, queue, or status may need to bypass the normal background path so they can reach a blocked or running agent safely.

Routing checklist

Verify the correct profile owns the running gateway.
Verify the adapter is connected with the intended credential.
Confirm sender authorization before creating agent work.
Build session keys through the official helper.
Preserve thread or topic identity where the platform supports it.
Keep inbound handling separate from outbound delivery.
Test running-agent commands and interruption.
Confirm cron delivery does not pollute interactive session history.

Pitfalls

Manually constructing a session key and dropping thread identity.
Running two profiles against the same bot credential without a scoped lock.
Treating an adapter connection as proof that authorization is correct.
Sending cron output through an interactive conversation history.
Restarting every gateway when only one profile is affected.

Verification steps

Check gateway status for the intended profile.
Send a harmless message from an authorized account.
Confirm the adapter produces the expected platform, chat, user, and thread identifiers.
Confirm the expected session is created or resumed.
Use a safe slash command and verify command dispatch.
Deliver a normal response and confirm the outbound message identifier.
Send a mid-turn stop or steering message in a disposable session.
Review delayed logs for duplicate delivery, authorization errors, or orphaned work.