Skip to main content

​
Before you start

  • Hermes Agent on Python 3.11 or newer, run once. Requires Hermes 0.19.0 or newer, tested through 0.21.3; newer minor versions log a warning and run, and versions below 0.19.0 are refused.
  • Node.js 22.22.3 or newer.
  • An existing Agent Token needs zero saved webhook subscriptions.

​
Connect

Run this in the folder where you work to connect hermes to Relay.
In an unlinked folder, this creates a new agent by default. If the folder is already linked, it uses that agent. Use --handle or --name to customize the new agent. start the gateway with hermes gateway run, then message the handle.

​
Install the plugin yourself

To keep the CLI away, install the Git-hosted plugin with Hermes’s own commands in the active profile:
Neither command asks a question, so both also run from a script. Install and enable are separate steps because install --enable skips the plugin’s Python dependencies when no terminal can answer, and enable prepares them without asking. Then set the token, the API address, and an absolute RELAY_STATE_DIR in the active profile, plus the optional RELAY_ALLOWED_CONTACTS.

​
Send it a message

Open Relay on your phone and message the handle. Hermes wakes up on its own and answers in the same chat. Keep the gateway running; it catches up later.

​
What it can do

From the connection code for hermes and the plugin’s adapter. Slash commands work the way they do on Telegram: Hermes runs them, and Hermes’s own allow_admin_from setting for the relayapp platform decides who may. When Hermes needs approval to run a tool, reply /approve, /approve session, /approve always or /deny.

​
When it fails

  • Startup fails naming the state folder: it belongs to another token; give this agent its own RELAY_STATE_DIR.
  • No reply yet. Run: relay watch @<handle> The gateway is not running, or a configured RELAY_ALLOWED_CONTACTS list excludes this sender.
Use the CLI guide for prompt, token, and restart errors.

​
Next steps