# How to set up Hermes Agent on iMessage with BlueBubbles

> Use an always-on Mac and BlueBubbles to connect iMessage to Hermes. Configure both network directions, authorize senders and check delivery.

Canonical: https://hermeswatcher.com/learn/hermes-agent-imessage-bluebubbles-setup  
Section: Learn · Messaging & the gateway  
Last reviewed: Oct 29, 2026  
Basis: Explained from the official Hermes Agent docs and repository (Nous Research). Steps follow the linked official sources.

## 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](https://hermeswatcher.com/learn/hermes-agent-imessage-photon-setup.md). 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](https://bluebubbles.app/) 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](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md).

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](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) for the shared gateway checklist, and [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md) 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](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/bluebubbles)

## Related guides

- [All messaging platforms](https://hermeswatcher.com/messaging.md)
- [Hermes Agent messaging gateway explained](https://hermeswatcher.com/learn/messaging-gateway-explained.md)
- [How to set up Hermes Agent on iMessage with Photon](https://hermeswatcher.com/learn/hermes-agent-imessage-photon-setup.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md)
- [Hermes Agent task finished but no message arrived](https://hermeswatcher.com/troubleshoot/task-finished-but-no-delivery.md)
- [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md)

## Related tools

- [Deployment: separate the agent host from its execution sandbox](https://hermeswatcher.com/tools/deployment.md)
- [Command approvals: decide what the agent may run unattended](https://hermeswatcher.com/tools/approvals-security.md)

## Sources

- [BlueBubbles iMessage setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/bluebubbles)
- [BlueBubbles setup source snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/bluebubbles.md)
- [Photon iMessage setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/photon)
- [Messaging gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)
- [Gateway access policy source](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/gateway/authz_mixin.py#L730-L773)
- [plugins/platforms/bluebubbles/adapter.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/plugins/platforms/bluebubbles/adapter.py)

---

HermesWatcher is an independent guide. It is not affiliated with or endorsed by Nous Research. The [official Hermes Agent documentation](https://hermes-agent.nousresearch.com/docs) and [repository](https://github.com/NousResearch/hermes-agent) from Nous Research are the authority; each page here lists the official sources it was written from. If this site and the official docs disagree, trust the official docs. Index for agents: https://hermeswatcher.com/llms.txt