Skip to content
RemoteClaw

iMessage

iMessage (legacy: imsg)

For new iMessage deployments, use BlueBubbles.

The imsg integration is legacy and may be removed in a future release.

Status: legacy external CLI integration. Gateway spawns imsg rpc and communicates over JSON-RPC on stdio (no separate daemon/port).

Pairing

Pairing — iMessage DMs default to pairing mode.

Quick setup

  1. Install and verify imsg

    Terminal window
    brew install steipete/tap/imsg
    imsg rpc --help

  2. Configure RemoteClaw

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

  3. Start gateway

    Terminal window
    remoteclaw gateway

  4. Approve first DM pairing (default dmPolicy)

    Terminal window
    remoteclaw pairing list imessage
    remoteclaw pairing approve imessage <CODE>

    Pairing requests expire after 1 hour.

Requirements and permissions (macOS)

  • Messages must be signed in on the Mac running imsg.
  • Full Disk Access is required for the process context running RemoteClaw/imsg (Messages DB access).
  • Automation permission is required to send messages through Messages.app.

Permissions are granted per process context. If gateway runs headless (LaunchAgent/SSH), run a one-time interactive command in that same context to trigger prompts:

Terminal window
imsg chats --limit 1
# or
imsg send <handle> "test"

Access control and routing

channels.imessage.dmPolicy controls direct messages:

  • pairing (default)
  • allowlist
  • open (requires allowFrom to include "*")
  • disabled

Allowlist field: channels.imessage.allowFrom.

Allowlist entries can be handles or chat targets (chat_id:*, chat_guid:*, chat_identifier:*).

Deployment patterns

Dedicated bot macOS user (separate iMessage identity)

Use a dedicated Apple ID and macOS user so bot traffic is isolated from your personal Messages profile.

Typical flow:

  1. Create/sign in a dedicated macOS user.
  2. Sign into Messages with the bot Apple ID in that user.
  3. Install imsg in that user.
  4. Create SSH wrapper so RemoteClaw can run imsg in that user context.
  5. Point channels.imessage.accounts.<id>.cliPath and .dbPath to that user profile.

First run may require GUI approvals (Automation + Full Disk Access) in that bot user session.

Remote Mac over Tailscale (example)

Common topology:

  • gateway runs on Linux/VM
  • iMessage + imsg runs on a Mac in your tailnet
  • cliPath wrapper uses SSH to run imsg
  • remoteHost enables SCP attachment fetches

Example:

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "~/.remoteclaw/scripts/imsg-ssh",
      remoteHost: "bot@mac-mini.tailnet-1234.ts.net",
      includeAttachments: true,
      dbPath: "/Users/bot/Library/Messages/chat.db",
    },
  },
}
#!/usr/bin/env bash
exec ssh -T bot@mac-mini.tailnet-1234.ts.net imsg "$@"

Use SSH keys so both SSH and SCP are non-interactive. Ensure the host key is trusted first (for example ssh bot@mac-mini.tailnet-1234.ts.net) so known_hosts is populated.

Multi-account pattern

iMessage supports per-account config under channels.imessage.accounts.

Each account can override fields such as cliPath, dbPath, allowFrom, groupPolicy, mediaMaxMb, history settings, and attachment root allowlists.

Media, chunking, and delivery targets

Attachments and media
  • inbound attachment ingestion is optional: channels.imessage.includeAttachments
  • remote attachment paths can be fetched via SCP when remoteHost is set
  • attachment paths must match allowed roots:
    • channels.imessage.attachmentRoots (local)
    • channels.imessage.remoteAttachmentRoots (remote SCP mode)
    • default root pattern: /Users/*/Library/Messages/Attachments
  • SCP uses strict host-key checking (StrictHostKeyChecking=yes)
  • outbound media size uses channels.imessage.mediaMaxMb (default 16 MB)
Outbound chunking
  • text chunk limit: channels.imessage.textChunkLimit (default 4000)
  • chunk mode: channels.imessage.chunkMode
    • length (default)
    • newline (paragraph-first splitting)
Addressing formats

Preferred explicit targets:

  • chat_id:123 (recommended for stable routing)
  • chat_guid:...
  • chat_identifier:...

Handle targets are also supported:

  • imessage:+1555...
  • sms:+1555...
  • user@example.com
Terminal window
imsg chats --limit 20

Config writes

iMessage allows channel-initiated config writes by default (for /config set|unset when commands.config: true).

Disable:

{
  channels: {
    imessage: {
      configWrites: false,
    },
  },
}

Troubleshooting

imsg not found or RPC unsupported

Validate the binary and RPC support:

Terminal window
imsg rpc --help
remoteclaw channels status --probe

If probe reports RPC unsupported, update imsg.

DMs are ignored

Check:

  • channels.imessage.dmPolicy
  • channels.imessage.allowFrom
  • pairing approvals (remoteclaw pairing list imessage)
Group messages are ignored

Check:

  • channels.imessage.groupPolicy
  • channels.imessage.groupAllowFrom
  • channels.imessage.groups allowlist behavior
  • mention pattern configuration (agents.list[].groupChat.mentionPatterns)
Remote attachments fail

Check:

  • channels.imessage.remoteHost
  • channels.imessage.remoteAttachmentRoots
  • SSH/SCP key auth from the gateway host
  • host key exists in ~/.ssh/known_hosts on the gateway host
  • remote path readability on the Mac running Messages
macOS permission prompts were missed

Re-run in an interactive GUI terminal in the same user/session context and approve prompts:

Terminal window
imsg chats --limit 1
imsg send <handle> "test"

Confirm Full Disk Access + Automation are granted for the process context that runs RemoteClaw/imsg.

Configuration reference pointers