Integrations · Hermes
Give your Hermes agent its own inbox
Install the Pidgeon plugin, and email to your agent’s address starts a Hermes conversation and is answered in the thread.
01 · Set it up
4 steps, about two minutes.
01 · Install the plugin
Python’s standard library only, for Hermes 0.22.2 or later, run on macOS and installed on Linux x64 and arm64.
hermes plugins install pidgeon-ai/pidgeon-python/hermes/pidgeon --enable02 · Give it a key
Create a key that reads and sends under Developers → API keys, limited to the agent’s address. PIDGEON_ALLOWED_USERS is who may write to the agent; anyone else gets nothing back.
PIDGEON_API_KEY=pgn_live_… PIDGEON_ALLOWED_USERS=you@example.com PIDGEON_ADDRESSES=agent@pidgeon.email03 · Start the gateway
Prints [Pidgeon] Connected when it is reading mail. Send the address an email: the agent answers in the thread, and a reply to that continues the same conversation.
hermes gateway run04 · Add the tools too
The plugin answers the mail in front of the agent. The MCP server gives it the rest: new addresses, search, and waiting for a verification code. You choose what it can do — read, read and send, or full access — and which address it reaches, or every address if you own the account. That becomes an API key under Developers → API keys → Connected apps, and Disconnect there ends it.
hermes mcp add pidgeon --url https://pidgeon.ai/api/mcp --auth oauth --connect-timeout 300
02 · Questions
Pidgeon in Hermes
- Do I need an API key?
- Not to connect: the client signs you in to Pidgeon, and the access you choose there becomes a key the client holds for you. A key of your own is for an agent with nobody there to sign in — read from your environment, so it never lands in a config file. Either can be scoped to one address and one level of access.
- How do I disconnect a client?
- Under Developers → API keys → Connected apps. Disconnect ends its access on the client’s next call, and nothing else you have connected is affected.
- Can my agent sign itself up?
- Yes. Paste “Read pidgeon.ai/skill.md and get yourself an email address.” into the agent. It creates the account with two HTTP calls and asks you for the six-digit code Pidgeon emails you.
- What can the agent do once it is connected?
- Create addresses, read and search mail, wait for the next message with any verification code already extracted, send and reply in threads, label and file messages, and hand a thread to a person. Every inbound message carries a Pidgeon Firewall verdict.
- Does new mail wake my Hermes agent?
- With the plugin, yes: an email to the address starts a conversation within seconds, one per email thread, and the answer goes back as a reply in that thread. The MCP server alone gives the agent tools but does not wake it.
- What happens to a prompt-injection email?
- Mail Pidgeon Firewall marks suspicious — addressed to an AI, or asking to send mail somewhere else — is held in the inbox and never reaches the agent. The agent reads the Firewall’s clean text, never raw HTML, and can only reply in the thread, so one email cannot make it write to anyone else.
- Can I use Hermes’s own email gateway instead?
- Yes, over IMAP and SMTP with an app password; the Hermes guide in the docs has the settings. It reads the raw message rather than the Firewall’s clean text, does not hold flagged mail, and keeps one conversation per sender rather than per thread.
03 · Elsewhere