Photon — iMessage Bridge for macOS

Photon — iMessage Bridge for macOS

If you’ve ever wanted to connect Hermes Agent to iMessage, you probably know the pain: Apple doesn’t exactly hand out APIs for sending texts. The usual workaround involves running your own Mac relay, dealing with webhooks, and babysitting a public URL. Not fun.

Enter Photon — a managed service that handles the Apple line allocation and abuse-prevention layer for you. Think of it as a bridge that connects Hermes to iMessage without all the plumbing. And the best part? The free tier is genuinely free.

No Webhooks, No Public URL

Photon is what we call a persistent-connection channel, just like Discord or Slack. That means no webhook setup, no public URL to expose, and no signing secret to manage. The connection stays open in both directions, so messages flow in and out automatically.

Under the hood, Hermes runs a small Node.js sidecar that holds a long-lived gRPC stream to Photon. Your Python agent talks to that sidecar over loopback — a local connection that never leaves your machine. The sidecar handles inbound messages, forwards them to your agent, and sends replies back out. If the stream ever drops, it reconnects automatically. You don’t have to think about it.

What You Need

Getting started is refreshingly simple:

• A Photon account — sign up at app.photon.codes
• Node.js 18.17 or newer on your PATH (check with node --version)
• A phone number that can receive iMessage (used to bind your account)

That’s it. No tunnels, no public URLs, no port forwarding.

First-Time Setup

The easiest way is to run the unified gateway wizard and pick Photon iMessage:

hermes gateway setup

Or run the Photon setup directly — the wizard calls the same flow anyway:

hermes photon setup --phone +15551234567

Here’s what happens, step by step:

1. Device login — opens a browser page for you to approve access
2. Finds or creates the “Hermes Agent” project on your account
3. Enables Spectrum and rotates the project secret
4. Registers your phone number as a Spectrum user (safe to re-run)
5. Prints your assigned iMessage line — the number people text to reach your agent
6. Installs sidecar dependencies with npm install

If you’re running in a read-only environment (like a Docker image or Nix), the sidecar automatically falls back to a writable mirror under ~/.hermes/photon/sidecar. You can pin a specific location with the PHOTON_SIDECAR_DIR env var.

Credentials are stored in ~/.hermes/.env — the same place every other channel keeps its tokens.

Who Can Message Your Agent?

Photon uses the same authorization model as every other Hermes channel. You have three options:

DM pairing (default). When an unknown number texts your Photon line, Hermes replies with a pairing code. Approve it with:

hermes pairing approve photon <CODE>

Use hermes pairing list to see pending codes and approved users.

Pre-authorize specific numbers (in ~/.hermes/.env):

PHOTON_ALLOWED_USERS=+15551234567,+15559876543

Open access (dev only, in ~/.hermes/.env):

PHOTON_ALLOW_ALL_USERS=true

One nice touch: when you set an allowlist, unknown senders are silently ignored rather than offered a pairing code. That signals you deliberately restricted access.

Require Mentions in Group Chats

By default, Hermes responds to every authorized DM and group message. If you want group chats to be opt-in, enable mention gating — DMs still always work:

gateway:
  platforms:
    photon:
      enabled: true
      require_mention: true

The defaults match “Hermes” and “@Hermes agent” variants. For a custom agent name, set regex patterns:

gateway:
  platforms:
    photon:
      require_mention: true
      mention_patterns:
        - '(?<![\w@])@?amos\b[,:\-]?'

You can also use env vars: PHOTON_REQUIRE_MENTION and PHOTON_MENTION_PATTERNS.

Start the Gateway

hermes gateway start

You’ll see something like:

[photon] connected — sidecar on 127.0.0.1:8789, streaming inbound over gRPC

Send an iMessage to your assigned number and Hermes will reply.

Status & Troubleshooting

Check everything with:

hermes photon status

This prints your saved credentials, sidecar health, registered number, and the assigned iMessage line. If a token and dashboard project are available, it even refreshes missing number rows from the dashboard without provisioning new lines.

Common issues:

• sidecar deps : ✗ run hermes photon install-sidecar — Node is installed but spectrum-ts isn’t. Run the suggested command.
• device token : ✗ missing — run hermes photon setup to log in.
• No iMessage line assigned yet — Spectrum is enabled but no line has been provisioned; re-run the setup.

Free to Start

Photon’s shared-line pool is free. No subscription required to send your first iMessage from Hermes — just a phone number we can bind to your account. Different recipients may see different sending numbers on the free tier, but each conversation stays stable. The paid Business tier gives every user the same dedicated number. The free tier is the recommended starting point.

So go ahead — bridge Hermes to iMessage without the headache. Your Mac relay can finally take a vacation.