mordred-discord-setup

name

mordred-discord-setup

description

Set up Hermes Agent as a Discord bot and connect it to the Mordred browser extension's end-to-end encryption. Use this when the user wants to add Discord to Hermes, create a Hermes Discord bot, or enable encrypted Discord channels with Mordred. Walks through the Discord Developer Portal, writes the bot token and allowed-user id to ~/.hermes/.env, invites the bot, starts the gateway, and verifies the bot comes online.

Mordred — Hermes Discord setup

You are configuring Hermes Agent to run as a Discord bot on this machine, then connecting it to the Mordred browser extension so a Discord channel can be end-to-end encrypted.

You have terminal access to the machine where Hermes runs. Your job is to do the Hermes-side configuration for the user and to guide them through the parts that only they can do in the Discord web UI (creating the app, copying the token).

Guardrails — read first

• Never print, echo, log, or paste the bot token into the chat, a file that gets committed, or any command that would appear in shell history in cleartext. Write it only to ~/.hermes/.env. When you need the user to give you the token, have them paste it and then immediately write it to the file — do not repeat it back.
• Never commit secrets. ~/.hermes/.env is not in a git repo; keep it that way. Do not add the token to any tracked file.
• The token grants full control of the bot. Treat it like a password. If it is ever exposed, tell the user to Reset Token in the Developer Portal.
• Only ever add the user's own Discord user id to DISCORD_ALLOWED_USERS unless they explicitly ask for more people. Without an allowlist Hermes denies everyone by design — do not "fix" that by allowing all users.

Prerequisites — verify before starting

Run these and confirm before doing anything else:

1. Hermes is installed and this is its home: check ~/.hermes/ exists and note whether ~/.hermes/.env and ~/.hermes/config.yaml are present.

   ls -la ~/.hermes/ 2>/dev/null && echo "--- .env keys (names only) ---" && \
     ( [ -f ~/.hermes/.env ] && sed -n 's/^\([A-Z_]*\)=.*/\1/p' ~/.hermes/.env || echo "(no .env yet)" )
   

   The sed prints only variable names, never values — safe to show.
2. The hermes CLI is available: command -v hermes || echo "hermes CLI not on PATH". If it is not on PATH, ask the user how they normally start the gateway (e.g. a venv, a systemd unit, python -m ...) and adapt the start/restart step accordingly.
3. The Discord platform plugin exists (it ships with Hermes). If hermes is present you can assume it does.

If Hermes is not installed here, stop and tell the user — this skill configures an existing Hermes install; it does not install Hermes.

Step 1 — Create the Discord application and bot (user does this)

Ask the user to do the following in their browser, and wait for them at each gate. Do not try to automate the Discord web UI.

1. Open the Discord Developer Portal: https://discord.com/developers/applications (sign in with their Discord account).
2. New Application → name it (e.g. "Hermes") → accept the terms → Create.
3. On General Information, copy the Application ID (a long number) and give it to you — you'll need it to build the invite URL. This is not a secret; it's fine for them to paste it in chat.
4. Left sidebar → Bot. Under Authorization Flow, set Public Bot = ON (needed for the Discord-provided invite link) and leave Require OAuth2 Code Grant = OFF.

Step 2 — Enable privileged intents (the #1 cause of a silent bot)

Still on the Bot page → Privileged Gateway Intents. Have the user toggle ON and Save Changes:

• Message Content Intent — required. Without it the bot connects but every message arrives with empty text, so it can never respond.
• Server Members Intent — required (needed to resolve users / for role-based auth).
• Presence Intent — optional, leave off.

Confirm with the user that they clicked Save Changes. If the bot later comes online but ignores messages, this is almost always the cause.

Step 3 — Get the bot token (handle securely)

On the Bot page → Token → Reset Token (enter 2FA if prompted). Discord shows the token once.

• Tell the user to paste the token to you.
• The moment you receive it, write it to ~/.hermes/.env (Step 5) — do not echo it, summarize it, or store it anywhere else.

Step 4 — Get the user's Discord user id

The user id controls who may talk to the bot.

1. Discord → Settings → Advanced → Developer Mode = ON.
2. Right-click their own username → Copy User ID (a long number like 284102345871466496). This is not a secret.

Step 5 — Write the Hermes config

Write the token and allowed user to ~/.hermes/.env without exposing the token. Prefer a heredoc/append that reads the value from a shell variable you set in a single, non-echoed step, or edit the file directly with your file tools. Ensure you do not clobber existing keys — append or update in place.

The two required keys:

DISCORD_BOT_TOKEN=<the token the user pasted>
DISCORD_ALLOWED_USERS=<the user's Discord user id>

Multiple users are comma-separated: DISCORD_ALLOWED_USERS=id1,id2.

Optional, only if the user asks:

• DISCORD_HOME_CHANNEL=<channel id> — where cron/notifications post (or the user can run /sethome in Discord later).
• DISCORD_FREE_RESPONSE_CHANNELS=<channel id> — channels the bot answers in without needing an @mention.

After writing, confirm the keys are present by name only:

sed -n 's/^\([A-Z_]*\)=.*/\1/p' ~/.hermes/.env | grep -E 'DISCORD_(BOT_TOKEN|ALLOWED_USERS)'

Do not print the values.

Step 6 — Invite the bot to the server

Build the invite URL from the Application ID (Step 1) with the recommended permissions (View Channels, Send Messages, Embed Links, Attach Files, Read Message History, Send Messages in Threads, Add Reactions):

https://discord.com/oauth2/authorize?client_id=<APPLICATION_ID>&scope=bot+applications.commands&permissions=274878286912

Give the user this URL. They open it → pick their server (they need Manage Server on it) → Authorize → solve the CAPTCHA. The bot then shows in the member list (offline until the gateway runs).

Step 7 — Start / restart the gateway and verify

Start (or restart, if it was already running) the Hermes gateway. Typical:

hermes gateway

If the user runs it another way (venv, systemd, tmux, background service), use their method. After start, verify:

• The process is up and the logs show a successful Discord login (no "Disallowed Intents" error — if you see that, an intent from Step 2 is off).
• In Discord the bot's member entry goes online.
• Ask the user to send a DM or @mention the bot in a channel it can see, and confirm it replies.

If it's online but silent → Message Content Intent is off (Step 2). If it never comes online → wrong token, or the gateway isn't running.

Step 8 — Connect Mordred E2E encryption

The bot now talks plaintext Discord. To make a channel end-to-end encrypted with the Mordred extension:

1. In the browser with the Mordred extension, open the Mordred popup → ⚙ Settings.
2. Under Encrypted channels, set the platform selector to Discord, type the channel name (e.g. secure-ops), and Add.
3. Open that channel in Discord. Messages you send are auto-encrypted (type, then Enter twice to send); a leading @mention stays plaintext so the bot is still pinged. Hermes decrypts inbound, replies encrypted, and Mordred decrypts it in place.

The bot must be allowed (its user is in the channel) and the user must be in DISCORD_ALLOWED_USERS. In server channels, @mention the bot (or make the channel free-response) so Hermes responds.

Done

Summarize for the user: which keys you wrote (names only), that the bot is online and replying, and that the Discord channel is registered in Mordred for E2E encryption. Remind them the bot token lives only in ~/.hermes/.env and should never be shared or committed.