Docs

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

Install

curl -fsSL https://bluetext.sh | sh  # CLI: ~/.local/bin/imx, no sudo, SHA-256 verified
brew trust bluetextrelay/tap && brew install bluetextrelay/tap/imx   # or with Homebrew
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://bluetext.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; TLS ends on your Mac, Tailscale can't read it	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, so only your keys and the rate limits protect it. Cloudflare and ngrok end TLS at their servers and could technically see traffic in transit; Tailscale Funnel ends it on your Mac. Setup for each, limits and the full privacy trade-offs: Connections and privacy.

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.
Attachment files: off for every key until you turn it on: the Attachment files toggle in Settings → Access, imx keys add … --attachments or imx keys attachments <name> on|off. Largest file 10 MB by default, 1–100 MB (imx attachment-cap <MB>).
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`
`get_attachment`	a file by the attachment id listed on its message: images as images (HEIC converted to JPEG), text through the privacy filter, other files as base64. Only for keys with attachment files on.

Messages list their attachments with an id, type, MIME type and size, never a path on your Mac. An attachment outside the key's threads or history start answers exactly like one that doesn't exist.

REST equivalents at /api/threads, /api/messages, /api/search, /api/new, /api/attachments/<id>; /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