Manage Messaging Access with Hermes DM Pairing

A bot with terminal, browser, file, or business tools must not accept commands from every account that can discover it. Hermes DM pairing gives unknown users a short-lived code that an operator approves from a trusted administrative surface. It is an authorization workflow, not merely an onboarding convenience.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/security#dm-pairing-system

Understand the authorization order

Hermes checks configured allowlists and approved pairing records before allowing a message to reach the agent. Chat-style direct-message platforms can reply to an unknown user with a pairing code; platforms can also be configured to stay silent or deny without pairing. Email is intentionally more conservative unless pairing is explicitly enabled.

Approve codes with hermes pairing approve <platform> <code>. Use hermes pairing list to inspect pending and approved users, revoke to remove access, and clear-pending to discard unused requests. Pairing codes are cryptographically random, rate-limited, and expire; approval should still verify the requester through a separate trusted channel.

Access checklist

Keep global allow-all disabled for tool-capable bots.
Choose pair, deny, or silent behavior per platform.
Verify the requester outside the bot conversation.
Approve from the host CLI or protected dashboard.
Record why access was granted and which platform identity was approved.
Revoke users who change roles or lose devices.
Clear stale pending codes after an incident or test.
Back up pairing state before upgrades when required.

Pairing versus allowlists

Use static allowlists when user IDs are known and tightly controlled. Use pairing when legitimate users need a practical enrollment flow. Both methods should be combined with least-privilege tools, group-session isolation, approval rules, and platform administration. Authorization to talk to the agent is not authorization for every high-impact action.

Common pitfalls

Approving a code solely because someone pasted it into the same DM.
Confusing a display name with a stable platform user ID.
Leaving test accounts approved.
Enabling allow-all to bypass a pairing problem.
Assuming revocation also deletes prior session history.
Copying pairing files into tickets or public repositories.

Verification steps

Send a DM from an unapproved test account.
Confirm the configured pair, deny, or silent behavior.
Approve the code from a trusted administrative surface.
Verify the exact platform identity can now access only intended tools.
Revoke the identity and confirm the next message is denied or re-paired.
Inspect pairing storage permissions and the administrative audit trail.