Skip to main content
Install openmailsh/hermes-plugin and mail to the agent’s address wakes it. Replies go out in the same thread.

​
Before you start

  • Hermes Agent, installed and working.
  • An OpenMail API key from the console. Any scope works.

​
Install

1

Install the plugin

2

Run setup

Paste the key. Setup picks your inbox, or creates one, then asks who may email the agent: a list of addresses, anyone your sender rules let through, or decide later.
3

Start the gateway

Already running? hermes gateway restart. Look for [OpenMail] Connected as <address> in the log.
Email the agent and it answers in the thread. Or ask it on your usual chat:
  • “What’s in the inbox since this morning?”
  • “Reply to Marc that Thursday works, and cc Jonas.”
  • “Sign up for the Linear newsletter and give me the confirmation code.”
Something off? hermes openmail doctor.

​
Modes

Setup picks channel. Change it with OPENMAIL_MODE in ~/.hermes/.env, or per inbox. notify needs a home channel: hermes gateway setup. Only mail from a person gets a reply. Notifications and verification codes reach the agent as information, so it never answers noreply@. Spam never reaches it.

​
Who can email the agent

Setup asks. Either list the addresses (OPENMAIL_ALLOWED_USERS), or let OpenMail decide and manage it under Allow/Block List in the console or with the CLI:
Blocked mail is dropped on the server; the agent never sees it.

​
Prompt injection

Replies go to the sender OpenMail recorded, not one the message claims. The model never sees the API key. Inbound mail can’t issue gateway commands. The agent can still start new threads; to stop that, make the inbox’s outbound policy an allowlist.

​
What the agent can do

Tools default to the agent’s own inbox. The bundled openmail skill teaches it the CLI for administration: sender rules, pods, deleting inboxes. Install the CLI separately.

​
Several inboxes

Say yes when setup offers the whole pod, and the agent runs every inbox in it, including ones it creates later. Each sender gets a conversation per inbox; replies leave from the inbox that received the mail. Set modes per inbox in ~/.hermes/config.yaml:

​
Subagents and Bots

Subagents run inside the agent and share its key and inboxes. To give one its own address, the agent creates an inbox and passes that inbox_id when it sends. A Bot is a separate Hermes profile with its own .env. Give it its own key:
Paste a pod or account key when asked. Setup stores a key that reaches only that inbox; the key you pasted is not kept.

​
Attachments

Text from PDF, DOCX, XLSX, PPTX, CSV, and images (OCR) reaches the agent inline, up to 8k characters per file and 24k total. Files without text arrive as files, so a vision model sees the picture. Outbound, the agent attaches files from ~/.hermes/media or ~/.hermes/output.

​
Scheduled jobs

--deliver openmail on a cron job emails its output to you; --deliver openmail:alice@x.com to anyone. Works with the gateway stopped.

​
Reliability

A restart replays missed mail and keeps replies in-thread. A rejected key stops the plugin instead of retrying; hermes openmail doctor says why.

​
Configuration reference

Setup writes ~/.hermes/.env. If you gave it an account key, it stores a narrower pod key instead. Each variable also works under platforms.openmail in config.yaml, lower-cased without the prefix. Skipping setup? OPENMAIL_API_KEY plus OPENMAIL_ALLOWED_USERS or OPENMAIL_ALLOW_ALL_USERS=true are enough. Scripted: hermes openmail setup --api-key <key> -y; add --allow-all to open the gate, --inbox <address> to run as one inbox.