Hermes Agent
Hermes Agent Gmail: three ways to connect it
Updated 17 November 2026
“Connect Hermes to Gmail” can mean three different things, and Hermes has a separate route for each. One lets the agent work inside your own mailbox. One lets it operate a mailbox through a command-line tool. One gives the agent its own address so that people can email it. This page sets out the steps for each and how to choose.
Facts come from the Hermes Agent 0.23.1 documentation: the Google Workspace skill page, the Email setup page, the Himalaya and Email Inbox Triage skill pages, and the guide “Give Your Agent Its Own Email Address”, all read on 17 November 2026.
Which route to use
The routes differ in whose mailbox is involved and where the credential lives. The Email setup page itself separates the last two: the Email platform lets people email the agent, while Himalaya lets the agent manage a mailbox from terminal tools.
| Route | What it is for | What you need | Where the credential is kept |
|---|---|---|---|
| Google Workspace skill | The agent searches, reads, replies and sends in your Gmail, and can use other Google services | A Google Cloud project with an OAuth client of type Desktop app | A token at ~/.hermes/google_token.json |
| Himalaya skill | The agent operates a mailbox through the himalaya command-line tool | The himalaya CLI, a config file and IMAP/SMTP credentials (for Gmail, an app password) | Wherever the config points: a file, pass, a keyring or another command |
| Email messaging platform | People email the agent and it replies in the same thread | A mailbox for the agent with IMAP enabled, plus an app password for Gmail | EMAIL_PASSWORD in ~/.hermes/.env |
- You want the agent to handle your own Gmail. The Google Workspace skill is the route built for that. The skill’s own setup notes add that if you need email only, you do not need it: Himalaya with a Gmail app password “takes 2 minutes” and needs no Google Cloud project.
- You want a mailbox the agent runs for you. Himalaya, ideally on a fresh account, as the Hermes guide recommends.
- You want to email the agent to give it work. The Email platform. The docs say you can run it alongside Himalaya, ideally on separate accounts.
The Google Workspace skill also covers Calendar and Drive; those have their own pages, Hermes Agent with Google Calendar and Hermes Agent with Google Drive.
Route one: the Google Workspace skill
The skill is bundled with Hermes. It uses OAuth2 with automatic token refresh, and it prefers the gws command-line tool when that is installed, falling back to Google’s Python client libraries. The documentation says setup is agent-driven: ask Hermes to set up Google Workspace and it walks you through the steps below.
- Say what you need. The skill asks which Google services you want. For Gmail plus Calendar it uses
--services email,calendar, so the consent screen asks only for what you need. It also asks whether your account uses Advanced Protection; if it does, your Workspace admin must allow the OAuth client ID first. - Create an OAuth client. In Google Cloud, create or pick a project, enable the Gmail API (and any others you want) in the API Library, then under Credentials create an OAuth 2.0 Client ID with application type Desktop app. If the app is still in Testing, add your Google account as a test user on the Audience page. Download the JSON file.
- Give Hermes the file. Run the setup script with the Python that Hermes itself uses, not a separate system Python. If Hermes cannot be imported, run
hermes setupfirst. Then:
GSETUP="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/setup.py"
$GSETUP --check
$GSETUP --client-secret /path/to/client_secret.jsonIn the Hermes CLI, a message that is only a path starting with / can be mistaken for a slash command, so put the path inside a sentence.
- Authorise. Generate the sign-in address, open it, approve, and paste back what the browser ends on:
$GSETUP --auth-url --services email,calendar --format json
$GSETUP --auth-code "THE_URL_OR_CODE_THE_USER_PASTED" --format json
$GSETUP --checkAfter you approve, the browser will probably fail to load http://localhost:1. The documentation says that is expected: copy the whole address from the address bar and give it to Hermes. --check should print AUTHENTICATED, and the token refreshes by itself from then on.
Day to day you just ask in chat. Underneath, the skill runs commands such as these. The skill sets GAPI as a shorthand for its API script:
GAPI="python ${HERMES_HOME:-$HOME/.hermes}/skills/productivity/google-workspace/scripts/google_api.py"
$GAPI gmail search "is:unread" --max 10
$GAPI gmail get MESSAGE_ID
$GAPI gmail reply MESSAGE_ID --body "Thanks, that works for me."
$GAPI gmail labelsSearch takes Gmail search operators such as from: and newer_than:1d. Replies are threaded automatically. The skill also supports gmail send with a custom --from display name; if you use a different address there, Gmail needs it set up as a Send As alias first. To remove access later, run $GSETUP --revoke.
Route two: the Himalaya skill
Himalaya is a command-line email client. The bundled skill teaches the agent its commands, so the agent works a mailbox from its terminal tools. It needs the himalaya CLI, a config file at ~/.config/himalaya/config.toml and IMAP/SMTP credentials. For Gmail, the Hermes guide says to enable IMAP in the provider’s settings, turn on two-factor authentication, and create an app password at myaccount.google.com/apppasswords.
curl -sSL https://raw.githubusercontent.com/pimalaya/himalaya/master/install.sh | PREFIX=~/.local sh
himalaya --version
himalaya account configureThe install line is the skill’s pre-built-binary route; Homebrew and cargo are the alternatives. The wizard needs interactive input, so Hermes runs it in PTY mode. You can instead write the config by hand. A Gmail-shaped sketch built from the docs:
[accounts.agent]
default = true
email = "my-agent@gmail.com"
backend.type = "imap"
backend.host = "imap.gmail.com"
backend.port = 993
backend.encryption.type = "tls"
backend.login = "my-agent@gmail.com"
backend.auth.type = "password"
backend.auth.cmd = "cat ~/.config/himalaya/app-password"
message.send.backend.type = "smtp"
message.send.backend.host = "smtp.gmail.com"
message.send.backend.port = 587
message.send.backend.encryption.type = "start-tls"
message.send.backend.login = "my-agent@gmail.com"
message.send.backend.auth.type = "password"
message.send.backend.auth.cmd = "cat ~/.config/himalaya/app-password"
folder.aliases.sent = "[Gmail]/Sent Mail"Keep the password file readable only by you (chmod 600), or use a secret-manager command such as pass show in place of cat. Then test from your own shell; once this works, the agent can use it too:
himalaya envelope listTwo details matter on Gmail. The skill says folder names that do not match Himalaya’s defaults need aliases, and Gmail is the common case, hence the [Gmail]/Sent Mail line. It also warns to write the key as folder.aliases.X directly under the account: in Himalaya v1.2.0 the older singular sub-section is silently ignored, saving to Sent then fails after the message has been delivered, and a caller that retries on that error sends the email twice.
This route is pull-based: the agent sees mail only when it looks. The Hermes guide suggests a scheduled job every 15 to 30 minutes (see Hermes Agent cron jobs) and says that if you need replies in a thread with sub-minute latency, the Email platform below is the better fit.
Route three: the Email platform
Here the agent gets its own mailbox. You send it an email and it replies in the same thread, using Python’s built-in IMAP and SMTP modules, with no extra packages. The prerequisites are a dedicated mailbox for the agent (the docs say not to use your personal email), IMAP enabled, and for Gmail an app password: turn on 2-Step Verification, create the password at the App Passwords page, and use its 16 characters instead of your normal one.
The quickest setup is the wizard; choose Email in the menu and answer the prompts:
hermes gateway setupOr add this to ~/.hermes/.env:
EMAIL_ADDRESS=hermes@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop
EMAIL_IMAP_HOST=imap.gmail.com
EMAIL_SMTP_HOST=smtp.gmail.com
EMAIL_ALLOWED_USERS=your@email.com,colleague@work.com
EMAIL_AUTHSERV_ID=mx.google.comThen start the gateway with hermes gateway to run it in the foreground, or hermes gateway install to install it as a user service. On startup the adapter tests the IMAP and SMTP connections, marks the existing inbox messages as seen so only new mail is processed, and starts polling. The default poll interval is 15 seconds (EMAIL_POLL_INTERVAL).
What to know about how it behaves:
- Allowed senders. With
EMAIL_ALLOWED_USERSset, mail from those addresses, from addresses inGATEWAY_ALLOWED_USERS, or from approved pairings can be processed, subject to sender authentication. With no allowlist, unknown senders are ignored silently.EMAIL_ALLOW_ALL_USERS=trueaccepts any sender and is not recommended. Entries match whole addresses. - Sender authentication. Hermes acts on a message only when your receiving server’s
Authentication-Resultsheader authenticates the From domain.EMAIL_AUTHSERV_IDmust be the exact id on the topmost such header; for Gmail the docs givemx.google.com. To find yours, open a delivered message’s raw source and copy the token before the first semicolon of that header. A matching id alone does not prove the header came from your server, so also check that your server removes any incomingAuthentication-Resultsheader that claims its id before adding its own. - Automated senders. Mail from
noreply@,mailer-daemon@and similar addresses, and mail carryingAuto-SubmittedorList-Unsubscribeheaders, or aPrecedence: bulkheader, is silently ignored. - Attachments. Images and documents are cached locally. To ignore them all, set
skip_attachments: trueunderplatforms.emailinconfig.yaml. - Other providers and relays. The page also covers Outlook and Microsoft 365 app passwords, and Proton Mail Bridge, which needs STARTTLS settings in
config.yaml.
Inbox triage on top of a route
Hermes bundles an Email Inbox Triage skill. It does not connect to anything itself: it owns the prioritising and reply policy, while connector skills such as himalaya and google-workspace do the mailbox work. So it sits on top of route one or two.
- Scope first. It fixes the account, folders or labels, time window, thread limit and allowed actions. The default is read and draft, not send or delete: “handle my inbox” does not imply permission to send.
- Whole threads. It reads complete threads rather than only the newest message, since earlier unanswered questions can sit upthread, and treats message content as data, never as instructions.
- Sorted by disposition. Each thread is labelled urgent reply, reply, action without reply, waiting, reference or noise, with a reason.
- Your voice. Before drafting, it samples your recent sent replies (20 to 50 where available) to match greeting, length and tone, and says so if the Sent folder cannot be read.
- Approval batch. It shows each proposed action with account, recipient, draft summary and risk, applies only what you approve, and reads the result back.
It is a procedure for the agent to follow, not a guarantee, so keep the approval step on. For the business-owner view of letting an assistant handle replies, see Can ChatGPT answer my emails?
Security points
- Sends need your approval. The Google Workspace skill’s rule is never to send email without confirming with you first, showing recipients and content. The Hermes guide says the same for Himalaya: have the agent draft and show you the message before sending, at least until you trust the pattern.
- Ask only for the scopes you need. The
--servicesoption narrows what the consent screen requests. Read it before you approve. The token stays in~/.hermes/google_token.json, and--revokeremoves access. - Use a dedicated mailbox for the agent. The Email page warns that the agent stores the password in
.envand has full inbox access over IMAP. Protect that file withchmod 600. An app password on a dedicated account is a small blast radius; your personal credentials are not. - Incoming mail is untrusted. The Hermes guide calls email an unauthenticated inbound channel and a prompt-injection surface. Do not let the agent act on instructions inside unsolicited mail, and keep the agent’s address off password resets, banking and account recovery.
- Limit who can email the agent. Keep
EMAIL_ALLOWED_USERSset. Pairing for unknown senders is opt-in, because shared inboxes hold unrelated unread mail that Hermes should not reply to.
Common errors
| Symptom | Fix, per the docs |
|---|---|
NOT_AUTHENTICATED | Run the Google Workspace setup steps. |
REFRESH_FAILED | The token was revoked or expired; redo the authorise steps. |
HttpError 403: Insufficient Permission | A scope is missing. Run $GSETUP --revoke, then authorise again with the right services. |
HttpError 403: Access Not Configured | Enable the API in the Google Cloud Console. |
Error 403: access_denied while signing in | Add your account as a test user on the Audience page. |
ModuleNotFoundError | Run $GSETUP --install-deps with the Python that Hermes uses, restart Hermes, then run the sign-in command again. |
| IMAP or SMTP connection failed at start-up (Email platform) | Check the host and port, and make sure IMAP is on. For Gmail the docs point to Settings, then Forwarding and POP/IMAP. |
| Authentication failed (Gmail) | Use an app password, not your normal one, with 2-Step Verification on first. |
| Messages not received | Check that EMAIL_ALLOWED_USERS includes the sender. If the gateway log says authserv-id is not configured, set EMAIL_AUTHSERV_ID. Check spam too. |
| Duplicate replies | Make sure only one gateway is running; hermes gateway status shows it. |
| Sent mail duplicated through Himalaya | Check the folder.aliases spelling above, and look in Sent before retrying a send. |
If a message is dropped with an unauthenticated From warning and your server stamps no Authentication-Results header, the docs offer require_authenticated_sender: false as an explicit opt-out, with the stated risk that From is then trusted as written.
Gmail on ReadyHermes
ReadyHermes runs your own Hermes Agent on our servers, always on, connected to the chat apps you choose. Its workspace has an Apps section that lists Gmail. You press Connect, sign in to your own Google account on Google’s sign-in page, approve and come back; the app then shows as connected, and you can disconnect from the same section whenever you like. You can also ask in chat, for example “Connect my Gmail”, and the assistant replies with a sign-in link. You do not create a Google Cloud project or OAuth client yourself. Read Google’s consent screen to see exactly what is being asked.
We have not tested the three Hermes routes on this page on a ReadyHermes assistant: not the bundled Google Workspace skill with your own OAuth client, not Himalaya, and not the Email platform. The workspace has no screen for them, and the chat apps we offer are Telegram, WhatsApp, Discord, WeChat and Lark, with no Email channel. If you want those exact routes, run Hermes yourself with the steps above (see install Hermes Agent), and self-hosting vs managed hosting helps you choose.
Whichever way you connect, we suggest having the assistant draft and ask you before anything is sent. ReadyHermes starts from US$3.99 a month (Lite) or US$6.99 (Pro), with US$1 of AI included every month and a 1-hour free trial.
Questions
How do I connect Hermes Agent to Gmail?
There are three routes. The Google Workspace skill uses OAuth and a Google Cloud OAuth client so the agent can work in your own Gmail. The Himalaya skill uses IMAP/SMTP with a Gmail app password. The Email messaging platform gives the agent its own mailbox that people can email. Pick by whose mailbox is involved.
Do I need a Google Cloud project to use Gmail with Hermes?
Only for the Google Workspace skill, which needs an OAuth client of type Desktop app. The skill's own notes say that if you need email only, Himalaya with a Gmail app password needs no Google Cloud project. The Email platform also uses an app password.
Can Hermes Agent send emails without asking me?
The Google Workspace skill's rules say never to send email without confirming with you first, and the inbox triage skill defaults to read and draft, not send. The Himalaya guide advises drafting and showing you the message before sending, at least until you trust the pattern.
What is the difference between the Himalaya skill and the Email platform?
Himalaya lets the agent operate a mailbox from terminal tools and needs the himalaya CLI, a config file and IMAP/SMTP credentials. The Email platform lets people email the agent and get a reply in the same thread, using Python's built-in IMAP and SMTP modules. Set EMAIL_ALLOWED_USERS to restrict who can interact with it.
Can I connect Gmail to Hermes on ReadyHermes?
Yes, through the Apps section of the workspace: press Connect on Gmail, sign in to your own Google account and approve, or ask in chat to connect it. We have not tested the Google Workspace skill, Himalaya or the Email platform on a ReadyHermes assistant, and there is no Email channel.