Setting Up Moltbot with iMessage: Complete macOS Integration Guide (2026)

What does Moltbot do?

At its core, Moltbot transforms your existing messaging apps into a command center for your digital life. It functions as a persistent, 24/7 AI agent that doesn't just "chat"—it acts. By living inside the communication tools you already use every day, it eliminates the cognitive overhead of switching between disconnected AI interfaces and your actual work.

The Multichannel Gateway

Moltbot can talk to you on almost any chat app you already use. Each "channel" connects via the Gateway, a central routing hub that normalizes incoming text and media. While technical support varies (text is universal, whereas media and reactions depend on the specific channel adapter), the experience remains consistent across platforms.

Method 1: BlueBubbles (Recommended)

BlueBubbles is currently the most robust way to bridge Moltbot with iMessage. It allows Moltbot to interact with Apple's Messages framework via a stable REST API, supporting advanced features like reactions, message edits, unsends, and high-fidelity media handling.

Step 1: Install BlueBubbles Server

Download and install the BlueBubbles Server on your macOS host. During setup, you'll need to create a Firebase project to handle the push notifications that wake up the system.

Step 2: Configure Moltbot Integration

In your Moltbot configuration, enable the BlueBubbles channel and provide your server details. You can find your API password in the BlueBubbles Server settings under the "API" tab.

{
  "channels": {
    "bluebubbles": {
      "enabled": true,
      "address": "http://192.168.1.50:1234",
      "password": "your-api-password",
      "webhookUrl": "http://moltbot-host:4444/bluebubbles"
    }
  }
}

Step 3: Register the Webhook

For real-time message receiving, you must point BlueBubbles to Moltbot's webhook endpoint. In the BlueBubbles Server UI, navigate to Settings → Webhooks and add your Moltbot gateway address.

Method 2: Native CLI (Legacy)

The native iMessage channel is an external CLI integration that works through a command-line tool called imsg. While simpler to set up for a single local Mac, it is less feature-rich than BlueBubbles and lacks support for modern iMessage features like reactions and tapbacks.

Quick Setup (iMsg CLI)

For Mac users who want to get started quickly using the CLI method, follow these steps:

brew install steipete/tap/imsg

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "/usr/local/bin/imsg",
      "dbPath": "/Users/<you>/Library/Messages/chat.db"
    }
  }
}

moltbot gateway

That's it! You can now send messages to yourself via iMessage, and Moltbot will respond.

Requirements & Permissions

Messaging integrations on macOS are unique because they tap into the native chat.db database. This requires specific system-level permissions that aren't typical for standard web services.

Configuration Writes

By default, iMessage is allowed to write configuration updates triggered by /config set|unset commands (requires commands.config: true).

If you want to prevent configuration changes via iMessage, disable this feature:

{
  "channels": {
    "imessage": {
      "configWrites": false
    }
  }
}

Dedicated Bot User Setup (Optional)

If you want the bot to send messages from a separate iMessage identity (keeping your personal Messages clean), create a dedicated macOS user.

Setup Steps

1. Create a dedicated Apple ID (e.g., [email protected])

   Apple may require a phone number for verification/2FA

2. Create a macOS user (e.g., clawdshome) and sign into it
3. Open Messages in that user and sign into iMessage using the bot Apple ID
4. Enable Remote Login: System Settings → General → Sharing → Remote Login
5. Install imsg in the bot user account:

   brew install steipete/tap/imsg

6. Set up SSH so ssh <bot-macos-user>@localhost true works without password
7. Create an SSH wrapper script (e.g., /path/to/imsg-bot):

   #!/usr/bin/env bash
   set -euo pipefail
   
   # Run interactive SSH once first to accept host keys:
   #   ssh <bot-macos-user>@localhost true
   exec /usr/bin/ssh -o BatchMode=yes -o ConnectTimeout=5 -T <bot-macos-user>@localhost \
     "/usr/local/bin/imsg" "$@"

8. Make the script executable:

   chmod +x /path/to/imsg-bot

9. Configure Moltbot to use the multi-account setup:

   {
     "channels": {
       "imessage": {
         "enabled": true,
         "accounts": {
           "bot": {
             "name": "Bot",
             "enabled": true,
             "cliPath": "/path/to/imsg-bot",
             "dbPath": "/Users/<bot-macos-user>/Library/Messages/chat.db"
           }
         }
       }
     }
   }

Remote/SSH Configuration (Optional)

If you want to run iMessage on another Mac (while the Gateway runs elsewhere), point cliPath to a wrapper that runs imsg on the remote macOS host over SSH.

SSH Wrapper Example

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Remote Attachments

When cliPath points to a remote host via SSH, attachment paths in the Messages database reference files on the remote machine. Moltbot can automatically fetch these over SCP by setting remoteHost:

{
  "channels": {
    "imessage": {
      "cliPath": "~/imsg-ssh",                     // SSH wrapper to remote Mac
      "remoteHost": "user@gateway-host",           // for SCP file transfer
      "includeAttachments": true
    }
  }
}

Remote Mac via Tailscale (Advanced)

If the Gateway runs on a Linux host/VM but iMessage must run on a Mac, Tailscale is the simplest bridge. The Gateway talks to the Mac over the tailnet, runs imsg via SSH, and SCPs attachments back.

┌──────────────────────────────┐          SSH (imsg rpc)          ┌──────────────────────────┐
│ Gateway host (Linux/VM)      │──────────────────────────────────▶│ Mac with Messages + imsg │
│ - moltbot gateway            │          SCP (attachments)        │ - Messages signed in     │
│ - channels.imessage.cliPath  │◀──────────────────────────────────│ - Remote Login enabled   │
└──────────────────────────────┘                                   └──────────────────────────┘
              ▲
              │ Tailscale tailnet (hostname or 100.x.y.z)
              ▼
        user@gateway-host

Concrete Configuration Example

{
  "channels": {
    "imessage": {
      "enabled": true,
      "cliPath": "~/.clawdbot/scripts/imsg-ssh",
      "remoteHost": "[email protected]",
      "includeAttachments": true,
      "dbPath": "/Users/bot/Library/Messages/chat.db"
    }
  }
}

Example Wrapper Script

#!/usr/bin/env bash
exec ssh -T [email protected] imsg "$@"

Access Control (DMs + Groups)

Direct Messages (DMs)

Default policy: channels.imessage.dmPolicy = "pairing"

• Unknown senders receive a pairing code
• Messages are ignored until approved (codes expire after 1 hour)
• Approve via:

  moltbot pairing list imessage
  moltbot pairing approve imessage <CODE>

Groups

Group policy options: open | allowlist | disabled

• groupAllowFrom controls who can trigger the bot in groups
• Mention gating uses agents.list[].groupChat.mentionPatterns
• iMessage has no native mention metadata, so regex patterns are required

Group-ish Threads

Some iMessage threads can have multiple participants but arrive with is_group=false depending on how Messages stores the chat identifier.

If you explicitly configure a chat_id under channels.imessage.groups, Moltbot treats that thread as a "group" for:

• Session isolation: Separate agent:<agentId>:imessage:group:<chat_id> session key
• Group allowlisting and mention gating behavior

{
  "channels": {
    "imessage": {
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["+15555550123"],
      "groups": {
        "42": { "requireMention": false }
      }
    }
  }
}

Media & Message Limits

Attachment Ingestion

Optional attachment ingestion via channels.imessage.includeAttachments

Media cap via channels.imessage.mediaMaxMb (default: 16 MB)

Text Chunking

Outbound text is chunked to channels.imessage.textChunkLimit (default: 4000 characters)

Optional newline chunking: Set channels.imessage.chunkMode="newline" to split on blank lines (paragraph boundaries) before length chunking

Addressing & Delivery Targets

For stable routing, prefer using chat_id over direct handles:

To list available chats:

imsg chats --limit 20

Configuration Reference

Complete list of available iMessage channel configuration options:

Frequently Asked Questions