How to set up Hermes Agent on iMessage with BlueBubbles

Which iMessage route?

BlueBubbles needs a Mac that stays on and signed into Messages with your Apple ID. Hermes docs describe BlueBubbles as free, open-source server software. You supply the Mac and keep it available.

Photon is a hosted vendor service that needs no Mac relay. It requires a Photon account and an iMessage-capable number. Hermes docs describe free shared lines, a paid dedicated-line tier, recipient-first contact on shared lines and metadata-only incoming attachments. See How to set up Hermes Agent on iMessage with Photon. Both routes need the Hermes host online.

What you need

BlueBubbles bridges Messages on your Mac to Hermes.

Hermes can run on the Mac or on another reachable machine. Starting with both on the same Mac uses the documented local webhook defaults and avoids the separate-machine network setup.

• A Mac running BlueBubbles Server 1.0.0 or newer, with your Apple ID signed into Messages.
• Hermes installed with a model provider and a gateway host that stays awake and online.
• The BlueBubbles server address and password, plus network access in both directions if Hermes runs on a different machine.
• Basic text and media can use a foreground, logged-in macOS user without the optional Private API helper. Background-user setups have additional requirements described below.

Prepare the Mac and BlueBubbles server

Download BlueBubbles Server from the BlueBubbles site↗ (opens in a new tab) and complete its setup wizard. Sign into Messages with the intended Apple ID and choose the connection method appropriate to your setup. The Hermes page lists local network, Ngrok, Cloudflare or Dynamic DNS options.

In BlueBubbles Server, open Settings, then API. Record the server URL and server password. The Hermes docs use http://192.168.1.10:1234 as a local-network example; replace it with the address of your server.

The account running BlueBubbles should remain logged in. A Mac sitting at the login screen, or a user switched into the background, can fail to send through AppleScript without the Private API helper. Keeping the Mac powered on alone is not sufficient.

Keep the server password secret. It is used for API access and in the registered webhook URL, so treat full callback URLs and logs containing them as credentials too.

Connect it to Hermes

Run the wizard, select BlueBubbles (iMessage), and enter the server URL and password. Alternatively, add the two settings below to ~/.hermes/.env, replacing the example address and password.

Setup saves credentials, but does not override an explicit platforms.bluebubbles.enabled: false in ~/.hermes/config.yaml. Check this setting if you previously used another iMessage bridge.

Gateway wizard

hermes gateway setup

~/.hermes/.env (manual alternative)

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

Check explicit enablement

hermes config get platforms.bluebubbles.enabled

The docs say true enables the adapter, an unset key lets credentials drive enablement, and false disables it. If it is explicitly false, change the existing platforms.bluebubbles.enabled setting to true. Avoid two active bridges handling the same account.

Choose who can talk to it

Set BLUEBUBBLES_ALLOWED_USERS in .env to the phone numbers or email addresses allowed to operate your agent. This allowlist is separate from the server password, which authenticates the bridge connection.

DM pairing is an alternative when the gateway policy offers a code. Inspect the request locally and approve only a sender you recognize. Restrictive allowlists or policies can suppress pairing codes, so the platform page's pairing example is not a promise for every configuration.

~/.hermes/.env (replace with your identities)

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

Inspect requests if using pairing

hermes pairing list

Approve a recognized sender

hermes pairing approve bluebubbles <CODE>

Optional group gate, merge into ~/.hermes/config.yaml

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

Leave BLUEBUBBLES_ALLOW_ALL_USERS unset. Authorized people can use the agent's configured tools, which may include terminal access.

Without mention gating, the docs say Hermes answers every authorized direct or group message. With it enabled, groups need a matching wake word such as Hermes or @Hermes agent. Direct messages still work normally; a mention does not grant sender access.

Check both network directions

Hermes calls BLUEBUBBLES_SERVER_URL to send messages through the Mac. In the other direction, BlueBubbles calls a webhook on Hermes to report new messages. A webhook is an HTTP callback carrying an event. Reaching the Mac's API does not establish that the Mac can reach this callback.

Hermes registers the webhook automatically when it connects. Do not create one manually as a normal setup step. The documented default listener is 127.0.0.1:8645, with path /bluebubbles-webhook. This loopback address is suitable when Hermes and BlueBubbles share a machine.

If they run on separate machines, set BLUEBUBBLES_WEBHOOK_HOST in .env to an address on the Hermes host that the Mac can reach, then restart the gateway. Check routing and firewall access to the configured port. The default port is 8645. A loopback listener cannot be reached from the other machine.

For the separate-machine setup, use a specific LAN address of the Hermes host, such as 192.168.1.20, for BLUEBUBBLES_WEBHOOK_HOST. Do not use 0.0.0.0, ::, 127.0.0.1 or localhost: the adapter registers those as http://localhost:8645/..., which points back to the Mac. This follows the official adapter code; shared-listener profiles use the gateway's logged profile URL instead.

The callback includes ?password=... because the BlueBubbles webhook API does not support custom headers. Keep the connection and its URLs private. This guide does not prescribe exposing that listener directly to the public internet.

Start the gateway and send your first message

Start the gateway with the Mac, Messages and BlueBubbles running. Inspect the gateway log in a second terminal. Look for both a BlueBubbles connection and successful webhook registration.

Send a short iMessage from another device using an allowed sender identity to the Mac's Messages account. Check that Hermes logs the incoming message and returns a reply. A webhook row or successful setup wizard alone does not establish delivery.

Run the gateway in the foreground

hermes gateway

Inspect the gateway log

hermes logs gateway

Ctrl+C stops the foreground gateway. Hermes removes its registered webhook on clean shutdown.

What it can do and the Private API caveat

The gateway table marks images, files, reactions and typing for BlueBubbles, but does not mark voice, threads or streaming. The platform page also describes sending and receiving audio, including voice attachments. Keep that distinction rather than treating the table as a complete voice specification.

• The page documents text, images, videos and documents. Incoming media is downloaded and cached locally for the agent. Outgoing text has Markdown stripped.
• Tapback reactions, typing indicators, read receipts and creating new chats by address require the optional Private API helper. Those features are conditional even though some are marked in the overview table.
• Basic text and media without the helper assume BlueBubbles can control Messages in a logged-in foreground macOS session. The docs say reliable sending from a background user or login-screen setup also requires the helper.
• Review BlueBubbles' linked helper instructions before choosing that advanced setup. This guide does not install or change the Mac's Private API configuration.

Keep it running

The bot is silent while its computer sleeps or is switched off. Keep the Hermes host awake and online whenever you need replies. A background service does not prevent sleep.

After the foreground check, stop that gateway before using the service commands below. The gateway service is launchd on macOS, systemd on Linux, or a logon Scheduled Task on Windows. This manages Hermes, not BlueBubbles or the Mac's Messages login.

Install the gateway service

hermes gateway install

Start it

hermes gateway start

Check it

hermes gateway status

Keep the Mac awake, the correct Messages account signed in, BlueBubbles running and the Hermes host online. If either host is asleep or off, replies cannot complete through this route. See How to run Hermes Agent 24/7 on a VPS or home server.

If Hermes runs on Windows, its Scheduled Task does not supervise a later gateway crash. Check status if replies stop.

Leave BLUEBUBBLES_HOME_CHANNEL empty until ordinary sending is reliable. The docs warn that restart notifications and recovered replies can pile up when Mac-side sending fails.

If it doesn't answer

• Cannot reach server: check the Mac is on, BlueBubbles is running, and the configured URL and password match the intended server and Apple ID.
• No incoming event: inspect hermes logs gateway for webhook registration errors. On separate hosts, check the callback bind address and Mac-to-Hermes reachability. Only inspect Settings, API, Webhooks in BlueBubbles if the log indicates registration failed.
• Setup succeeded but no adapter: check hermes config get platforms.bluebubbles.enabled. An explicit false setting wins over saved credentials.
• Sends hang or recovered replies repeat: inspect Mac-side AppleScript permissions and whether the BlueBubbles user is in the foreground. Do not repeatedly restart into a failing home-channel delivery loop.
• Duplicate replies: check for two active iMessage bridges. The platform page also records a separate session-addressing issue, so duplicates are not always fixed by configuration. Follow its linked issue reports if the problem remains.
• Check Hermes Agent bot not responding in your chat app for the shared gateway checklist, and Hermes Agent task finished but no message arrived if processing finished but the reply did not arrive.

Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

Official Hermes iMessage with BlueBubbles docs↗ (opens in a new tab)

Related guides

• All messaging platforms
• Hermes Agent messaging gateway explained
• How to set up Hermes Agent on iMessage with Photon
• Hermes Agent bot not responding in your chat app
• Hermes Agent task finished but no message arrived
• How to run Hermes Agent 24/7 on a VPS or home server

Spotted something wrong or out of date? Tell us on X at @HermesWatcher↗ (opens in a new tab) and we will fix it.

New Hermes Agent updates every day on X. Follow @HermesWatcher