Hermes Photon iMessage

Decision needed: Make iMessage via Photon a default channel on all RE Reset client Hermes agents, same class as Telegram/Slack — not optional experiment.

What Photon is

Photon is a managed service that allocates and runs iMessage lines for agents. Hermes talks to Photon through a platform plugin (photon-platform) and a small Node sidecar that runs the TypeScript spectrum-ts SDK over a long-lived gRPC stream.

Client iPhone  ←iMessage→  Photon cloud (line owner)
                              ↕ gRPC (spectrum-ts)
                         Node sidecar (on Hermes box, :8789)
                              ↕ loopback HTTP
                         PhotonAdapter → Hermes gateway → agent tools

Photon vs BlueBubbles

Capabilities (current plugin)

• DM and group iMessage
• Inbound media / voice notes (downloaded for the agent; ~20 MB cap)
• Outbound text + attachments
• Markdown replies (native iMessage rendering)
• Optional reaction tapbacks as processing status
• Allowlist + home channel for cron / notifications

Prerequisites

• Hermes Agent ≥ 0.17 (Photon plugin present; 0.18+ preferred)
• Node.js on the box (sidecar)
• Gateway running / able to restart
• Client phone numbers for allowlist (E.164)
• Photon account access for RE Reset ops (app.photon.codes)

One-time setup per client box

1. SSH / open Orgo terminal on the client Hermes box as the agent user (usually root on Orgo).
2. Run setup (replace with the client principal’s phone for home/allowlist, or the ops number you use for testing first):

   hermes photon setup --phone +1XXXXXXXXXX
   hermes photon status
   hermes gateway restart   # or start if not running

3. Confirm credentials landed:

   grep '^PHOTON_' ~/.hermes/.env
   # expect PHOTON_PROJECT_ID and PHOTON_PROJECT_SECRET

4. Record the assigned iMessage line printed by setup — that is the number the client texts.
5. Set allowlist to only approved client numbers (and Jake/ops if needed):

   # ~/.hermes/.env
   PHOTON_ALLOWED_USERS=+1CLIENT,...,+1OPS
   PHOTON_HOME_CHANNEL=+1CLIENT_OR_SPACE_ID
   PHOTON_ALLOW_ALL_USERS=false
   PHOTON_REQUIRE_MENTION=true   # recommended for groups

6. Restart gateway again after env edits.
7. Smoke test from an allowlisted phone:
   • Send “ping” DM → agent replies
   • Send a photo → agent sees media
   • Unknown number → ignored / no agent run
   • Gateway restart → still receives after ~30s
8. Store in 1Password / client vault: Photon project id (non-secret ok), note of assigned line, allowlist, date enabled. Never put project secret in client-facing docs.

After Hermes updates

hermes update
hermes photon install-sidecar   # if iMessage breaks after spectrum-ts bumps
hermes photon status
hermes gateway restart

Security defaults (non-negotiable)

• Never leave PHOTON_ALLOW_ALL_USERS=true on a client box.
• Allowlist = client principals only (+ optional RE Reset ops).
• Treat Photon project secret like any API key.
• Prefer shared free line for POC; dedicated line if client volume / reliability requires it.

Troubleshooting

Talk to your RE Reset agent on iMessage

Your AI agent can text you the same way a teammate would — in the blue iMessage bubbles.

1. Save the number we send you (e.g. “RE Reset Agent — [Company]”).
2. Text that number from your phone (the one we allowlisted).
3. Start with something simple: “What’s on my plate today?” or a real work question.
4. You can send photos, voice notes, and documents when relevant.
5. For group chats: include the agent and mention it if we configured mention mode.

If messages don’t go through: text Jake or your RE Reset contact on Slack/Telegram and we’ll check the line within one business day.

Copy block for onboarding email / portal

Your Hermes agent is now on iMessage.

Number: [ASSIGNED_LINE]
Text from: [YOUR ALLOWLISTED PHONE]

Try: "Summarize my open priorities"
Questions? Reply here or ping us on Slack.

1. Pilot: one client box (lowest risk) — full smoke checklist.
2. Document: lock SOP + client how-to in Process Library / brain.
3. Template: add Photon stage to golden template / install-box.
4. Backfill: Travis → Matt → Elise → Atomic → remaining Orgo clients.
5. Default: every new client box ships with Photon before “live” handoff.

Spaces: RE Reset (Internal) · Marcus Board · Process Library → Tool Setup Guide

• Photon product: photon.codes
• Photon dashboard: app.photon.codes
• Hermes plugin path: plugins/platforms/photon/
• Setup command: hermes photon setup --phone +E.164
• Status: hermes photon status