How to Add iMessage to Hermes Agent (No Mac Required)

Short answer: install hermes-imessage, add your Claw Messenger API key, enable the Hermes toolset, and start the Hermes gateway. Your agent gets a real messaging line without running a Mac, a SIM, or a self-hosted Apple relay.

The package source is on GitHub at emotion-machine-org/hermes-imessage.

Does Hermes Agent support iMessage without a Mac?

Yes. Hermes Agent can use iMessage without a Mac when it runs through the hermes-imessage plugin and the Claw Messenger managed relay. Hermes Agent by Nous Research stays on the same Linux server, VPS, or local machine where it already runs.

The BlueBubbles problem

Hermes Agent also has a BlueBubbles path, but that path still depends on a Mac running Messages.app and BlueBubbles Server. For Hermes users who want a server-first setup, the current BlueBubbles adapter has known open bugs that can block inbound messages.

• Issue #9263: webhook registration can fail with 400 Bad Request.
• Issue #9265: webhook dispatch can fail with 401 Unauthorized.
• Issue #8514: chatGuid can be null, which can route replies to the wrong chat.

Claw Messenger bypasses that adapter. Hermes calls the hermes-imessage plugin, the plugin calls Claw Messenger, and Claw Messenger handles iMessage, RCS, and SMS delivery.

What Hermes gets from Claw Messenger

The Hermes package turns Claw Messenger into a Hermes toolset. Once it is enabled, a Hermes agent can receive messages sent to your Claw Messenger number and reply from that same number.

• Receive iMessage, RCS, and SMS in Hermes.
• Reply in direct messages and existing group chats.
• Create new group chats with the Hermes tool.
• Receive media attachments as cached local files.
• Run on server environments where Messages.app is unavailable.

Why this matters for Hermes users

Hermes is built around agent workflows, but messaging is usually the hard part. iMessage normally requires Apple hardware and local Messages.app access. Claw Messenger handles that relay layer and gives Hermes a plain package integration instead.

Use this path when you want your Hermes agent to join real text conversations, reply to users, or handle lightweight operational workflows from a phone number people already trust.

Install the Hermes iMessage package

Install the package into the Hermes Agent virtual environment:

uv pip install --python ~/.hermes/hermes-agent/venv hermes-imessage

Then enable the Hermes Claw Messenger toolset:

hermes tools enable hermes-claw-messenger

Add the Hermes configuration

Add the plugin to ~/.hermes/config.yaml. The package name is hermes-imessage, while the internal module is hermes_claw_messenger.

plugins:
  - hermes_claw_messenger

platforms:
  claw_messenger:
    toolsets:
      - hermes-claw-messenger

Add your Claw Messenger API key before starting the gateway:

export CLAW_MESSENGER_API_KEY="cm_live_xxxxxxxxxxxxxxxx"
hermes gateway start

Optional settings

Most users only need the API key. For stricter deployments, Hermes can also pass a server address, preferred service, allowed user list, and default home channel through environment variables.

Hermes iMessage versus a Mac relay

A self-hosted Mac relay can work if you already own and maintain a Mac. For most Hermes users, the managed path is simpler because the agent can run where Hermes already runs.

Common setup checks

• Confirm hermes-imessage installs into the Hermes virtual environment.
• Confirm hermes tools enable hermes-claw-messenger succeeds.
• Confirm CLAW_MESSENGER_API_KEY is set in the shell that starts Hermes.
• Send a test message to your Claw Messenger number and watch the Hermes gateway logs.
• Reply from Hermes and confirm the message arrives on the phone.

When to use this

Use Hermes iMessage when the agent needs to live in real messaging threads: personal assistants, support triage, scheduling, lightweight operations, group updates, or alert follow-up. Use the lower-level REST API when you are not running Hermes and only need direct programmatic sends.

Prefer OpenClaw instead? Follow the OpenClaw iMessage setup guide.