Hermes Agent iMessage Setup: 3 Ways to Connect

Hermes Agent can live inside iMessage — either as a contact you text from your iPhone, or as an assistant working inside your own Messages app. This guide covers all three official routes for connecting Hermes to iMessage: Photon (no Mac required), BlueBubbles (Mac-based), and the imsg CLI skill, with the exact commands, quotas, and gotchas for each.

What Is Hermes Agent?

Hermes Agent is an open-source, self-hosted AI agent released by Nous Research in February 2026. It runs on your own hardware, keeps persistent memory, and writes its own skill files when it notices repeated task patterns. It connects to iMessage, Telegram, Discord, Slack, WhatsApp, Signal, email, and a dozen other platforms from a single gateway process — and it passed 140,000 GitHub stars within months of release, making it one of the most-used open agents in the world.

Gateway or Skill? Two Different Things "Hermes iMessage" Can Mean

Before picking a setup, know which of these you actually want:

• A gateway gives Hermes its own iMessage line. You (and anyone you authorize) text the agent like a regular contact. Photon and BlueBubbles are gateways.
• The imsg skill lets Hermes operate your Messages.app on a Mac — reading history, watching chats, and sending messages as you. The agent works inside your existing conversations instead of having its own number.

Most people searching for "Hermes iMessage" want the first one. Options 1 and 2 below are gateways; option 3 is the skill.

Option 1: Photon (No Mac Required)

Photon is a managed service that handles Apple line allocation so you don't have to run your own Mac relay. Your Hermes install can run on Linux, Windows, macOS, a home server, or any cloud box.

Requirements

• A Photon account (sign up at app.photon.codes)
• Node.js 18.17 or newer
• A phone number that can receive iMessages

Setup

# One-command setup (device-code login, project
# creation, and number registration are automatic)
hermes photon setup --phone +15551234567

# Start the gateway
hermes gateway start

# Check credentials, sidecar health, and your
# assigned iMessage line
hermes photon status

Authorize who may talk to your agent — DM pairing is the default:

hermes pairing approve photon <CODE>

Or pre-authorize numbers in ~/.hermes/.env with PHOTON_ALLOWED_USERS=+15551234567.

Limits to know

• Free tier uses a shared line pool: 5,000 messages/day per server and 50 new conversations/day per shared line. Dedicated numbers require the paid Business tier.
• Outbound attachments (images, voice, video, documents) work; inbound attachments arrive as metadata only — Hermes can't read the file bytes yet.

Option 2: BlueBubbles (Mac-Based Gateway)

BlueBubbles is a free, open-source macOS server that bridges iMessage to anything — including Hermes. You get a real iMessage line backed by your own Apple ID, at the cost of keeping a Mac online 24/7.

Setup

1. Install BlueBubbles Server (v1.0.0+, webhooks required) on the Mac, sign in with an Apple ID, and pick a connection method (local network, Ngrok, Cloudflare, or Dynamic DNS).
2. Copy the server URL and password from BlueBubbles Settings → API.
3. Run hermes gateway setup, select BlueBubbles (iMessage), and enter both — or set them in ~/.hermes/.env:

BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=your-server-password

Then authorize users (same hermes pairing approve bluebubbles <CODE> flow) and start with hermes gateway run.

Group chats

To keep Hermes quiet in group threads unless mentioned, enable mention-gating in ~/.hermes/config.yaml:

platforms:
  bluebubbles:
    enabled: true
    extra:
      require_mention: true

Troubleshooting

"Cannot reach server" usually means the Mac is asleep or a firewall is in the way. If messages stop arriving, check webhook registration in BlueBubbles Settings → API → Webhooks and tail hermes logs -f. Reactions, typing indicators, and read receipts additionally need the BlueBubbles Private API helper — basic messaging works without it.

Option 3: The imsg CLI Skill (Hermes Inside Your Own Messages)

Hermes ships a bundled apple-imessage skill built on the same imsg CLI that OpenClaw uses. Instead of giving the agent its own number, this lets Hermes read and send messages through your Messages.app on a Mac.

# Install imsg
brew install steipete/tap/imsg

# What Hermes can then do:
imsg chats --limit 10 --json      # list your chats
imsg history --chat-id 1 --json   # read history
imsg watch --chat-id 1            # monitor new messages
imsg send --to "+14155551212" --text "Hello!"

Requirements: a Mac with Messages signed in, Full Disk Access for your terminal, and Automation permission for Messages.app. Hermes asks for explicit approval before messaging unknown numbers, and group chat management (adding/removing members) isn't supported.

Things to Know Before You Commit

All three routes leave you operating infrastructure. Photon is the lightest, but you're on a shared line pool with daily quotas. BlueBubbles means a Mac that can never sleep, an Apple ID dedicated to the bot, and webhook debugging when things go quiet. The imsg skill grants an AI agent read access to your entire message history — consider a dedicated macOS user account. And whichever route you pick, model API costs are on you.

Is Self-Hosting Hermes Right for You?

Hermes is a serious agent framework, and connecting it to iMessage is genuinely useful. But if what you want is simply AI in your Messages app, compare the effort honestly:

Choose Hermes if: You want a self-improving agent you fully control, you're comfortable in a terminal, and you like the idea of an AI that writes its own skills on your server.

Choose a zero-setup option if: You want iMessage AI that just works — no gateway, no pairing codes, no quotas to think about.

Frequently Asked Questions

What is Hermes Agent?

Hermes Agent is an open-source, self-hosted AI agent released by Nous Research in February 2026. It runs on your own server, connects to iMessage and a dozen other messaging platforms through a gateway process, and builds its own skill files from repeated tasks.

Can Hermes Agent use iMessage without a Mac?

Yes. The Photon channel handles Apple line allocation as a managed service, so Hermes can send and receive iMessages from Linux, Windows, or any cloud server. Only BlueBubbles and the imsg skill require a Mac.

Is Photon iMessage for Hermes free?

There's a free tier on a shared iMessage line pool — 5,000 messages/day per server and 50 new conversations/day per line. Dedicated numbers require the paid Business tier.

What's the difference between the gateway and the imsg skill?

A gateway (Photon or BlueBubbles) gives Hermes its own number that you text like a contact. The imsg skill lets Hermes act inside your own Messages.app, reading and sending as you.

Is there a simpler alternative for iMessage AI?

Yes. Contact-based iMessage bots like iChatWithGPT require zero setup — text a number and start chatting. No server, no configuration, works on any iPhone, Apple Watch, or CarPlay.

Related

• OpenClaw iMessage Setup: Build Your Own AI Text Bot with imsg CLI
• iMessage Bot: Best AI Chatbots for Texting (2026 Guide)
• How to Text ChatGPT in iMessage: Complete Guide