mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-04-25 00:51:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions
hermes-agent/website/docs/user-guide/messaging/bluebubbles.md
Teknium 7120d6cdd6
fix(bluebubbles): add missing integration points and documentation (#6460) 
- hermes_cli/skills_config.py: add platform label for per-platform skill config
- gateway/session.py: add to PII-safe platforms (no mention system)
- website/docs/user-guide/messaging/bluebubbles.md: full setup guide
- website/sidebars.ts: sidebar navigation entry
- 10 docs pages: add BlueBubbles to all platform enumerations
  (env vars, toolsets, cron delivery, gateway internals, etc.)
2026-04-09 00:19:05 -07:00

4.8 KiB
Raw Blame History

BlueBubbles (iMessage)

Connect Hermes to Apple iMessage via BlueBubbles — a free, open-source macOS server that bridges iMessage to any device.

Prerequisites

  • A Mac (always on) running BlueBubbles Server
  • Apple ID signed into Messages.app on that Mac
  • BlueBubbles Server v1.0.0+ (webhooks require this version)
  • Network connectivity between Hermes and the BlueBubbles server

Setup

1. Install BlueBubbles Server

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).

2. Get your Server URL and Password

In BlueBubbles Server → Settings → API, note:

  • Server URL (e.g., http://192.168.1.10:1234)
  • Server Password

3. Configure Hermes

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

4. Authorize Users

Choose one approach:

DM Pairing (recommended):

hermes pairing generate bluebubbles

Share the pairing code — the user sends it via iMessage to get approved.

Pre-authorize specific users:

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

Open access:

BLUEBUBBLES_ALLOW_ALL_USERS=true

5. Start the Gateway

hermes gateway run

Hermes will connect to your BlueBubbles server, register a webhook, and start listening for iMessage messages.

How It Works

iMessage → Messages.app → BlueBubbles Server → Webhook → Hermes
Hermes → BlueBubbles REST API → Messages.app → iMessage
  • Inbound: BlueBubbles sends webhook events to a local listener when new messages arrive. No polling — instant delivery.
  • Outbound: Hermes sends messages via the BlueBubbles REST API.
  • Media: Images, voice messages, videos, and documents are supported in both directions. Inbound attachments are downloaded and cached locally for the agent to process.

Environment Variables

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_SEND_READ_RECEIPTS No true Auto-mark messages as read

Features

Text Messaging

Send and receive iMessages. Markdown is automatically stripped for clean plain-text delivery.

Rich Media

  • Images: Photos appear natively in the iMessage conversation
  • Voice messages: Audio files sent as iMessage voice messages
  • Videos: Video attachments
  • Documents: Files sent as iMessage attachments

Tapback Reactions

Love, like, dislike, laugh, emphasize, and question reactions. Requires the BlueBubbles Private API helper.

Typing Indicators

Shows "typing..." in the iMessage conversation while the agent is processing. Requires Private API.

Read Receipts

Automatically marks messages as read after processing. Requires Private API.

Chat Addressing

You can address chats by email or phone number — Hermes resolves them to BlueBubbles chat GUIDs automatically. No need to use raw GUID format.

Private API

Some features require the BlueBubbles Private API helper:

  • Tapback reactions
  • Typing indicators
  • Read receipts
  • Creating new chats by address

Without the Private API, basic text messaging and media still work.

Troubleshooting

"Cannot reach server"

  • Verify the server URL is correct and the Mac is on
  • Check that BlueBubbles Server is running
  • Ensure network connectivity (firewall, port forwarding)

Messages not arriving

  • Check that the webhook is registered in BlueBubbles Server → Settings → API → Webhooks
  • Verify the webhook URL is reachable from the Mac
  • Check hermes gateway logs for webhook errors

"Private API helper not connected"

  • Install the Private API helper: docs.bluebubbles.app
  • Basic messaging works without it — only reactions, typing, and read receipts require it