# How to set up Hermes Agent on iMessage with Photon

> Connect iMessage through Photon's hosted service without a Mac relay. Set access controls and understand shared-line and incoming-attachment limits.

Canonical: https://hermeswatcher.com/learn/hermes-agent-imessage-photon-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?

With Photon, you text a phone number that Photon gives you. The agent replies through that managed line. It does not run inside your own Apple ID. Your messages pass through Photon's service on their way to Hermes. Check its privacy terms before sending sensitive information.

Photon is a hosted vendor service: no Mac relay is needed, but you need a Photon account and an iMessage-capable phone number. Hermes docs describe free shared lines and a paid Business dedicated line. Shared lines need the recipient to message first; incoming attachments are metadata-only, so the agent cannot read their contents.

BlueBubbles runs through your own Mac, which must stay on and signed into Messages. For that route, see [How to set up Hermes Agent on iMessage with BlueBubbles](https://hermeswatcher.com/learn/hermes-agent-imessage-bluebubbles-setup.md). Both routes also need the Hermes host online for replies.

## What you need

Hermes uses a small Node helper process, called a sidecar, to maintain the Photon connection. The gateway manages that process.

This route does not need a webhook, public HTTPS URL or tunnel. Those are ways of accepting incoming internet requests; Photon uses a persistent connection instead.

- Hermes installed with a model provider on the computer or server that will run the gateway.
- A Photon account at [the Photon dashboard](https://app.photon.codes/) and a phone number that can receive iMessage, used to bind your account.
- Node.js. Hermes can provision its managed Node with the command below. The adapter can also use Node from PATH.

Provision managed Node if needed:

```
hermes pm install node
```

## Connect the Photon account

Run the gateway wizard and choose Photon iMessage. Alternatively, use the direct setup command below with your own iMessage-capable number in international format, including `+` and the country code. Choose one setup route.

Follow the device-login approval at `app.photon.codes`. Setup prepares your Photon account for Hermes, registers your phone number and installs the helper it needs. It also creates a new secret, so run it again only when you mean to. Record the assigned iMessage line it prints: that is the number you text to reach the agent.

Gateway wizard:

```
hermes gateway setup
```

Direct alternative, replace the example number:

```
hermes photon setup --phone +15551234567
```

Setup writes `PHOTON_PROJECT_ID` and `PHOTON_PROJECT_SECRET` into `~/.hermes/.env`. The saved device token and dashboard project metadata live in `~/.hermes/auth.json`. Protect both files and keep their credentials out of chat, screenshots and source control.

On a read-only installation, the documented sidecar fallback is a writable copy under `~/.hermes/photon/sidecar`. Setup still needs to install that helper's dependencies.

## Choose who can talk to it

For a personal setup, add your own number to `PHOTON_ALLOWED_USERS` in `~/.hermes/.env`. This allowlist is the explicit list of people allowed to use your agent. Replace the example numbers; use full international numbers (E.164 format: a plus sign, country code and number), separated by commas.

Even with an allowlist, an unknown sender might receive a pairing code. A code does nothing until you approve it, so approve only people you recognize.

~/.hermes/.env (restrict access):

```
PHOTON_ALLOWED_USERS=+15551234567,+15559876543
```

Inspect pairing requests if using pairing:

```
hermes pairing list
```

Approve only a sender you recognize:

```
hermes pairing approve photon <CODE>
```

Leave `PHOTON_ALLOW_ALL_USERS` unset. Access to the agent can include access to its terminal and other tools.

By default, Hermes answers authorized direct and group messages. To require a wake word in groups, the docs expose `PHOTON_REQUIRE_MENTION` in `.env`; enable it with the boolean value `true`. Defaults match Hermes and @Hermes agent. This gate does not replace sender authorization and does not gate direct messages.

## Start the gateway and send your first message

For an initial foreground check, run the gateway and leave the terminal open. Hermes starts the Node helper automatically. In another terminal, inspect Photon status to see the registered phone number, assigned line and sidecar health.

From your allowed iMessage number, text a short message to the assigned line. On a shared line, you must message it first before the agent can send to you. Look for the inbound event and a reply. An assigned number or stored credential alone does not show that messages are being delivered.

Run the gateway in the foreground:

```
hermes gateway
```

Inspect Photon status:

```
hermes photon status
```

`Ctrl+C` stops the foreground gateway and its managed helper. Complete your own message check before using this channel for scheduled notifications.

## What it can do and where it stops

The gateway table marks voice, images, files, reactions and typing for Photon. It does not mark threads or streaming. The platform page adds an important direction limit: incoming attachments provide filenames and media types only. The agent cannot read the incoming image, document or audio bytes through this adapter.

- Outgoing images, voice notes, videos and documents are documented. Captions arrive as a separate iMessage bubble after the media.
- The platform page also documents native polls and message effects. These are channel capabilities, not a promise that every model response will use them.
- Read receipts are sent after an inbound message is forwarded to Hermes, before the model or tools finish. Read is not proof that the task completed. Set `PHOTON_READ_RECEIPTS=false` in `.env` if you want to disable those receipts.

## Shared lines, quotas and cost

Hermes docs describe a free shared-line pool with no subscription needed for the first message. Different recipients may see different sending numbers, while each conversation keeps its number. The paid Business tier provides a dedicated number shared across your recipients. Check the current dedicated-line price in your Photon account.

The same docs report 5,000 messages per server per day and 50 new-conversation initiations per shared line per day. They separately state that a shared line cannot initiate contact with a new recipient at all until that recipient texts the line. Treat the recipient-first rule as a requirement, not as permission to cold-message 50 people.

These are the terms reported in the Hermes documentation, not an independent check of your Photon account's commercial terms. Confirm the current plan and limits in your account before relying on them.

## 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 installing and starting a background service. The gateway owns the sidecar; cron jobs and standalone sends also reuse that running helper. A hosted Photon line does not keep your Hermes agent running for you.

Install the gateway service:

```
hermes gateway install
```

Start it:

```
hermes gateway start
```

Check it:

```
hermes gateway status
```

For hosting choices, see [How to run Hermes Agent 24/7 on a VPS or home server](https://hermeswatcher.com/learn/run-hermes-agent-24-7.md).

The service uses systemd on Linux, launchd on macOS, or a logon Scheduled Task on Windows. The Windows launcher does not supervise later gateway crashes, so check status if replies stop.

## If it doesn't answer

Start with `hermes photon status`. Check the registered number, assigned line, saved login and sidecar health before changing access controls.

- Missing sidecar dependencies: run the documented repair command below. The platform page says a PATH Node installation must be 18.17 or newer if the helper will not start.
- Missing device token or no assigned line: run `hermes photon setup` and inspect your Photon dashboard. Setup rotates the project secret; do not treat it as a read-only status check.
- Unknown sender ignored: check the E.164 number in the allowlist. An unknown sender may be ignored or receive a pairing code. A code grants no access until you approve it.
- Standalone send rejected or gateway reported down: start the gateway, then check the helper. A new shared-line recipient must send the first message.
- Incoming file cannot be read: this is a documented adapter limit, not a reason to open access or reinstall. See [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.md) for the broader gateway checklist.

Repair sidecar dependencies if status requests it:

```
hermes photon install-sidecar
```

## Official docs

Reviewed Oct 29, 2026 against the official Hermes docs.

[Official Hermes iMessage with Photon docs](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/photon)

## 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 BlueBubbles](https://hermeswatcher.com/learn/hermes-agent-imessage-bluebubbles-setup.md)
- [Hermes Agent bot not responding in your chat app](https://hermeswatcher.com/troubleshoot/gateway-bot-not-responding.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

- [Photon iMessage setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/photon)
- [Photon setup source snapshot](https://github.com/NousResearch/hermes-agent/blob/088f657ecf77674c7b8e2ededf4e3576d82e042c/website/docs/user-guide/messaging/photon.md)
- [BlueBubbles iMessage setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/bluebubbles)
- [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)
- [gateway/authz_mixin.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/gateway/authz_mixin.py)
- [plugins/platforms/photon/adapter.py](https://raw.githubusercontent.com/NousResearch/hermes-agent/main/plugins/platforms/photon/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