Connect Hermes to iMessage with BlueBubbles

BlueBubbles gives Hermes an iMessage path by connecting the gateway to a BlueBubbles Server that you operate. Treat that server as a privileged bridge: it can relay personal conversations, so access policy and delivery verification belong in the initial setup rather than a later hardening pass.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/messaging/bluebubbles

Understand the boundary

BlueBubbles Server runs on a compatible Mac and exposes the iMessage connection. Hermes connects with the server URL and password, then maps inbound conversations to gateway sessions. The bridge is not a general public chatbot endpoint. Keep the server updated, limit network exposure, and never paste its password into chat, screenshots, or a public configuration file.

For direct messages, DM pairing is the safest default: an unknown sender receives a short pairing flow and an operator approves the identity. A narrow pre-authorized list is useful for a known household or team. Open access is suitable only for an isolated development test.

Setup checklist

• Install and verify BlueBubbles Server on the intended Mac.
• Record the server URL and password in a secret-safe local location.
• Run hermes gateway setup and select BlueBubbles.
• Choose DM pairing or a narrow sender allowlist.
• Decide whether group chats require an explicit mention.
• Start the gateway and inspect the BlueBubbles adapter status.
• Test one inbound direct message and one outbound reply.
• Test media separately if the workflow depends on attachments.

Design group-chat behavior deliberately

Group threads need a stronger noise policy than direct messages. Requiring a mention prevents ordinary family or team conversation from waking the agent. Give each group an understandable purpose, keep autonomous delivery to a designated home channel, and avoid sending long operational reports into social threads.

Session continuity should also be intentional. Confirm whether a conversation maps to a stable per-chat session and test that two unrelated chats do not share context.

Common pitfalls

• Publishing the BlueBubbles password in an environment example or support bundle.
• Exposing the server directly to the internet without understanding its controls.
• Enabling open access because pairing was not tested.
• Letting every group message trigger the agent.
• Assuming a delivered text proves image or attachment delivery works.
• Restarting every gateway platform when only BlueBubbles needs attention.

Verification steps

1. Start the gateway and confirm the BlueBubbles adapter reports ready without printing secrets.
2. Message the bot from an unauthorized identity and confirm the configured pairing or denial behavior.
3. Approve a test identity, send a plain-text message, and verify the reply appears in the same thread.
4. Send a group message without a mention, then with a mention, and confirm the chosen policy.
5. Restart the adapter and confirm the authorized identity and session mapping remain correct.
6. Review logs for message content, phone-number exposure, repeated reconnects, or delivery errors before production use.