Photon — iMessage Bridge for macOS

Imagine having a personal assistant who can text you back on iMessage — but instead of a human, it’s your AI agent. That’s exactly what Photon does for Hermes Agent. Think of it like a friendly translator sitting between your Mac and your iPhone, making sure the two can chat without you needing to run a complicated server or open any ports.

What Is Photon, Really?

Photon is a managed service that connects Hermes to iMessage. You don’t need to own a Mac relay or deal with Apple’s strict messaging rules. Photon handles the tricky parts — like phone number allocation and spam prevention — so you can focus on building your agent.

The best part? It’s free to start. Photon uses a shared pool of iMessage numbers for its free tier. That means the person texting your agent might see different sender numbers, but each conversation stays stable. If you need a dedicated number for business, there’s a paid tier — but the free option is perfect for experimenting.

How It Works (Without the Tech Overload)

Photon uses a persistent connection, much like Discord or Slack. No webhooks, no public URLs, no signing secrets to manage. Instead:

• Hermes runs a small Node.js sidecar (a helper program) that talks to Photon.
• The sidecar listens for incoming iMessages and passes them to your agent.
• Your agent replies, and the sidecar sends the response back through Photon.

It’s like having a mailroom clerk who receives letters, hands them to you, and then mails your replies — all automatically.

What You Need Before Starting

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

That’s it. No public URL, no tunnel, no router configuration.

First-Time Setup (Takes Less Than 5 Minutes)

The easiest way is to use the guided wizard:

hermes gateway setup

Then pick Photon iMessage from the list.

Or, if you prefer the direct route, run this one-liner (replace the phone number with yours):

hermes photon setup --phone +15551234567

Here’s what happens behind the scenes:

1. A device login opens a browser page for you to approve.
2. Hermes finds or creates a project on your Photon account.
3. It enables Spectrum (Photon’s messaging layer) and rotates your project secret.
4. Your phone number gets registered as a Spectrum user.
5. You’ll see your assigned iMessage line — that’s the number people text to reach your agent.
6. The sidecar dependencies are installed automatically.

If you’re running in a Docker container or a read-only file system, don’t worry — the sidecar automatically falls back to a writable folder under ~/.hermes/photon/sidecar. You can also set a custom location with PHOTON_SIDECAR_DIR.

Your credentials are saved safely in ~/.hermes/.env, just like every other channel Hermes supports.

Summary and a Practical Tip

Photon makes iMessage integration genuinely simple. No server maintenance, no public IP, no Apple headaches. You get a working bridge in minutes, and the free tier is enough to start building.

Practical tip: Before you send your first test message, make sure your phone number is correct and can actually receive iMessage. Use the same number you registered with — otherwise, you might wonder why your agent isn’t replying. And if you ever get stuck, just re-run the setup command; it’s designed to be safe to repeat.

Now go ahead — give your agent a phone number and let the texting begin! 📱🤖