website/docs/user-guide/messaging/bluebubbles.md
Connect Hermes to Apple iMessage via BlueBubbles — a free, open-source macOS server that bridges iMessage to any device.
Download and install from bluebubbles.app. Complete the setup wizard — sign in with your Apple ID and configure a connection method (local network, Ngrok, Cloudflare, or Dynamic DNS).
In BlueBubbles Server → Settings → API, note:
http://192.168.1.10:1234)Run the setup wizard:
hermes gateway setup
Select BlueBubbles (iMessage) and enter your server URL and password.
Or set environment variables directly in ~/.hermes/.env:
BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=your-server-password
By default, Hermes responds to every authorized BlueBubbles/iMessage DM or group message. To make group chats opt-in, enable mention gating:
platforms:
bluebubbles:
enabled: true
extra:
require_mention: true
With require_mention: true, DMs still work normally, but group-chat messages are ignored unless they match a mention pattern. If you do not configure custom patterns, Hermes uses conservative defaults for Hermes and @Hermes agent variants.
For a custom agent name, set regex patterns:
platforms:
bluebubbles:
extra:
require_mention: true
mention_patterns:
- '(?<![\w@])@?amos\b[,:\-]?'
Choose one approach:
DM Pairing (recommended): When someone messages your iMessage, Hermes automatically sends them a pairing code. Approve it with:
hermes pairing approve bluebubbles <CODE>
Use hermes pairing list to see pending codes and approved users.
Pre-authorize specific users (in ~/.hermes/.env):
[email protected],+15551234567
Open access (in ~/.hermes/.env):
BLUEBUBBLES_ALLOW_ALL_USERS=true
hermes gateway run
Hermes will connect to your BlueBubbles server, register a webhook, and start listening for iMessage messages.
iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage
| Variable | Required | Default | Description |
|---|---|---|---|
BLUEBUBBLES_SERVER_URL | Yes | — | BlueBubbles server URL |
BLUEBUBBLES_PASSWORD | Yes | — | Server password |
BLUEBUBBLES_WEBHOOK_HOST | No | 127.0.0.1 | Webhook listener bind address |
BLUEBUBBLES_WEBHOOK_PORT | No | 8645 | Webhook listener port |
BLUEBUBBLES_WEBHOOK_PATH | No | /bluebubbles-webhook | Webhook URL path |
BLUEBUBBLES_HOME_CHANNEL | No | — | Phone/email for cron delivery |
BLUEBUBBLES_ALLOWED_USERS | No | — | Comma-separated authorized users |
BLUEBUBBLES_ALLOW_ALL_USERS | No | false | Allow all users |
BLUEBUBBLES_REQUIRE_MENTION | No | false | Require a mention pattern before responding in group chats |
BLUEBUBBLES_MENTION_PATTERNS | No | Hermes wake words | JSON array, newline-separated, or comma-separated regex patterns for group mention matching |
Auto-marking messages as read is controlled by the send_read_receipts key under platforms.bluebubbles.extra in ~/.hermes/config.yaml (default: true). There is no corresponding environment variable.
Send and receive iMessages. Markdown is automatically stripped for clean plain-text delivery.
Love, like, dislike, laugh, emphasize, and question reactions. Requires the BlueBubbles Private API helper.
Shows "typing..." in the iMessage conversation while the agent is processing. Requires Private API.
Automatically marks messages as read after processing. Requires Private API.
You can address chats by email or phone number — Hermes resolves them to BlueBubbles chat GUIDs automatically. No need to use raw GUID format.
Some features require the BlueBubbles Private API helper:
Without the Private API, basic text messaging and media still work.
hermes logs gateway for webhook errors (or hermes logs -f to follow in real-time)