Sókrates Wiki

Hermes Access Control and DM Pairing

2 min read

Hermes Access Control and DM Pairing

Summary

Hermes enforces default-deny access control at the gateway level: all users are denied unless explicitly allowlisted or approved via DM pairing. This page covers the normative constraints (Law) on access control configuration and the DM pairing workflow. For the full defense-in-depth security model (dangerous command approval, container isolation, MCP credential filtering, prompt injection detection), see Hermes Agent Security Model.

Details

Configuration and Allowlists

Access is statically configured using platform-specific environment variables in ~/.hermes/.env, ensuring user IDs from one service do not inadvertently grant access to another. Supported configuration variables:

  • TELEGRAM_ALLOWED_USERS
  • DISCORD_ALLOWED_USERS
  • SIGNAL_ALLOWED_USERS
  • SMS_ALLOWED_USERS
  • EMAIL_ALLOWED_USERS
  • MATTERMOST_ALLOWED_USERS
  • MATRIX_ALLOWED_USERS
  • DINGTALK_ALLOWED_USERS

A global GATEWAY_ALLOWED_USERS variable permits specific IDs across all platforms. GATEWAY_ALLOW_ALL_USERS=true exists but is strongly discouraged in production. If no allowlists are configured and GATEWAY_ALLOW_ALL_USERS is not set, all users are denied and a warning is logged at startup.

For the full authorization chain evaluation order, see Hermes Agent Security Model.

DM Pairing Workflow

DM pairing provides dynamic user onboarding without requiring upfront user IDs in NixOS configuration. The workflow:

  1. Initiation: An unknown user sends a DM to the bot. The gateway generates a one-time pairing code.
  2. Approval: An administrator approves via CLI: hermes pairing approve [channel] [code]
  3. Management:
    • hermes pairing list — displays all pending and approved users.
    • hermes pairing revoke [channel] [user_id] — immediately removes a user’s access rights.

The unauthorized_dm_behavior setting (global or per-platform) controls whether unknown DMs receive a pairing code (pair, the default) or are silently dropped (ignore).

Pairing code security constraints (alphabet, TTL, rate limiting, lockout thresholds, file permissions) are documented in Hermes Agent Security Model.

No interaction with the underlying system or the Eidos knowledge graph occurs until a trusted administrator has verified the identity of the requester.

Graph View

Backlinks