BlueBubbles — AI on iMessage | Easy Understand Hermes Agent

Imagine your favorite group chat, but instead of just your friends, there’s a super-smart assistant who can look things up, write drafts, and help you plan—all without leaving your Messages app. That’s exactly what Hermes Agent can do for iMessage, and BlueBubbles is the bridge that makes it possible.

What is BlueBubbles?

BlueBubbles is a free, open-source server that runs on your Mac. It connects to the Messages app on that Mac and exposes a way for other devices (and Hermes) to send and receive iMessages. Think of it as a friendly translator: your Mac speaks iMessage, Hermes speaks HTTP, and BlueBubbles translates between them.

What You’ll Need

Before we start, make sure you have:

A Mac that’s always on (even when you’re sleeping)
Your Apple ID signed into Messages on that Mac
BlueBubbles Server v1.0.0 or newer installed (from bluebubbles.app)
Your Hermes installation ready to go

Step 1: Install BlueBubbles Server

Download and install BlueBubbles from bluebubbles.app. During setup, you’ll sign in with your Apple ID and pick a connection method. For beginners, local network is easiest—it just means Hermes and your Mac are on the same Wi-Fi.

Step 2: Grab Your Server URL and Password

Open BlueBubbles Server → Settings → API. You’ll see two important things:

Server URL – looks like http://192.168.1.10:1234
Server Password – a secret key you’ll need later

Keep these handy—you’ll need them in the next step.

Step 3: Connect Hermes to BlueBubbles

The easiest way is to use the setup wizard. Open your terminal and run:

hermes gateway setup

Choose BlueBubbles (iMessage) and paste in your server URL and password.

Prefer editing files? Open ~/.hermes/.env and add:

BLUEBUBBLES_SERVER_URL=http://192.168.1.10:1234
BLUEBUBBLES_PASSWORD=your-server-password

Step 4: Decide Who Can Talk to Your AI

You don’t want strangers using your AI. Hermes gives you two options:

Option A – Pairing (recommended for beginners):
When someone messages you, Hermes sends them a code. You approve it with:

hermes pairing approve bluebubbles <CODE>

Option B – Pre-approve specific people:
Add their iMessage email or phone number to your .env file:

BLUEBUBBLES_ALLOWED_USERS=user@icloud.com,+15551234567

Step 5: Start the Gateway

Now the fun part. Run:

hermes gateway run

Hermes will connect to BlueBubbles, register a webhook (a real-time notification system), and start listening. No polling, no delays—just instant iMessage magic.

How It Works (In Plain English)

When someone texts you: iMessage → BlueBubbles server → webhook → Hermes (instant delivery)
When Hermes replies: Hermes → BlueBubbles REST API → Messages app → your friend’s iPhone
Media works too: images, voice notes, videos, and documents flow both ways automatically

A Quick Tip for Group Chats

By default, Hermes responds to every message in a group chat. That can get noisy. To make it only respond when someone mentions you (like @Hermes or @amos), add this to your Hermes config:

platforms:
  bluebubbles:
    extra:
      require_mention: true

DMs still work normally—only group chats become opt-in.

Wrapping Up

You now have a personal AI assistant living inside iMessage. It can answer questions, help draft messages, or run automations—all from your favorite chat app.

Practical tip: Start with just one or two approved users (like yourself and a close friend). Test it with simple requests first, then expand. And remember: your Mac needs to stay awake and connected for BlueBubbles to work—so plug it in and let the magic flow.