Docs

Everything the app does, the imx command line does too. Pick whichever you prefer; they share one config.

Install

curl -fsSL https://bluetextrelay.com/install.sh | sh   # CLI: ~/.local/bin/imx, no sudo, SHA-256 verified
imx setup

Read install.sh first if you like; it is short. Or use the app: Download the DMG, drag to Applications, open. Grant Full Disk Access when asked (System Settings → Privacy & Security → Full Disk Access → Blue Text Relay on → relaunch). Allow Contacts if you want names instead of phone numbers.

Messages in iCloud should be on (Messages → Settings → iMessage) so every thread syncs to this Mac.

Headless (no window)

curl -fsSL https://bluetextrelay.com/install.sh | sh
imx setup             # access check, pick threads, first key, remote mode
imx service install   # run at login via launchd, restart if it stops
imx status            # one screen: license, server, threads, keys, remote

Give the imx binary Full Disk Access (the path service install prints). Turn on automatic login and stop the Mac from sleeping (sudo pmset -a sleep 0).

Connect an agent

Create a key (Settings → Access → New Key, or imx keys add "Claude on the mini" --threads ID,ID --daily 500). The token is shown once. Then:

# Claude Code
claude mcp add --transport http imessage http://<mac>.<tailnet>.ts.net:8766/mcp --header "Authorization: Bearer <token>"

# Claude Desktop, Cursor, others (mcpServers block)
{ "mcpServers": { "imessage": { "type": "http", "url": "http://<mac>.<tailnet>.ts.net:8766/mcp",
  "headers": { "Authorization": "Bearer <token>" } } } }

Each key has a Copy agent briefing button: a page of instructions for the agent describing exactly what it can see and how to behave. Hand that to the agent along with the token.

Remote access

Mode	Reach	Setup
This Mac only	localhost	none
Tailscale (recommended)	your own devices, end-to-end encrypted (WireGuard); Tailscale can't read it	one click: install/sign in, URL appears
Tailscale Funnel	public HTTPS on your ts.net name; decrypted at Tailscale's Funnel servers	one click; your tailnet must allow Funnel
Cloudflare Quick Tunnel	public HTTPS, random URL; decrypted at Cloudflare's edge	one click, no account
Cloudflare Tunnel (a domain you own)	public HTTPS on your own Cloudflare account; decrypted at Cloudflare's edge	sign in, create, hostname, start
ngrok	public HTTPS; decrypted at ngrok's servers	paste authtoken once

Public modes put the endpoint on the internet and terminate TLS at the provider (Tailscale Funnel, Cloudflare or ngrok), so that provider could technically see traffic in transit; only your keys and the rate limits protect the address. Prefer Tailscale, which is end-to-end encrypted between your own devices. imx remote <mode> does the same from a terminal.

Controls

Threads: check in the app, or imx threads / imx setup.
History limit: the "All history" button next to a synced thread, or imx history <thread-id> 2026-10-01 (off to clear).
Keys: scope, daily cap, per-call cap, expiry, revoke. imx keys add|list|revoke|delete|usage.
Privacy filter: Settings → General, or imx privacy on|off. On by default; replaces anything that looks like a credential with [redacted: …].
Audit log: ~/Library/Logs/Blue Text Relay/access.log. Key, source, tool, thread, count, status. Never message text.

MCP tools

`list_threads`	ids, names, participants, counts, `history_starts`, `me`
`get_messages`	JSON, oldest first; `since`/`until`/`limit`
`get_transcript`	Markdown grouped by day
`search_messages`	case-insensitive substring, newest first
`get_new_messages`	polling with an exact `next_cursor`

REST equivalents at /api/threads, /api/messages, /api/search, /api/new; /health needs no key.

License

A license key is required. Without one the server answers HTTP 402 with a JSON body that tells an agent exactly how to help you buy and activate; exports pause too. Enter your key in Settings → General → License or imx license <KEY>. Verified offline.

Questions

Does the Mac need to be awake? Yes. The endpoint is live only while the app or service runs. Agents are told to back off and retry.

Can it send messages? No. Read-only, by design.

What does Apple think? It uses the Full Disk Access permission Apple provides for exactly this. It reads your own data on your own Mac, bypasses nothing, and modifies nothing.

More: Privacy · Security model · For agents · Support