Messages Bridge — Setup (Mac Mini)

This machine runs messages-bridge (Docker) — all channels except iMessage. Use the checklist below to provision fast, then use the chat panel to get help while you do it.

messages-bridge mode (no iMessage) setup page + live helper chat requires Docker Desktop

0) Preflight

Install

  • Docker Desktop (required)
  • Ollama (recommended for fast local replies): confirm http://localhost:11434
  • Optional: GitHub access to clone the repo

Tokens you might need

  • Slack: SLACK_BOT_TOKEN + SLACK_APP_TOKEN (Socket Mode)
  • Telegram: TELEGRAM_BOT_TOKEN
  • Twilio: TWILIO_ACCOUNT_SID, TWILIO_AUTH_TOKEN, TWILIO_PROXY_NUMBER
  • Email worker (optional): EMAIL_WORKER_URL, EMAIL_BRIDGE_SECRET

0.5) Integration checklist (all supported)

Use these pages to enable every integration this bridge supports (messages-bridge mode = no iMessage). Each link opens a step-by-step setup guide.

Slack (Socket Mode)channel

Enable Slack inbound/outbound via Socket Mode tokens.

Open: Slack integration →

Telegram Bot APIchannel

Webhook, registration flow, and deep-link auth.

Open: Bot setup guide →

Email workerchannel

Send/receive email via Cloudflare worker + allowlist mapping.

Open: Email integration →

Twilio SMSchannel

Inbound webhooks + outbound SMS + group messaging plan.

Open: Twilio project plan →

Cloudflare tunnel / domaininfra

Expose the bridge securely to the internet on a stable domain.

Open: Tunnel provisioner →

launchd (autostart)infra

Keep services alive across reboots (bridge, tunnel, watchdog).

Open: launchd guide →

Env transfer protocolops

How to move tokens/config safely between machines.

Open: Env transfer →

macOS node playbookops

Full Mac mini provisioning checklist (long-form).

Open: Mac mini playbook →

Hivemind (agent-to-agent)integration

Multi-agent messaging & coordination.

Open: Hivemind setup →

Dev cookbook / endpointsreference

Quick reference for webchat + bridge endpoints.

Open: Dev cookbook →

Access roles / permissionssecurity

Who can access what pages and why.

Open: Access roles →

Status dashboardops

Check whether services are up and reachable.

Open: Agent status →
If you’re not sure which page to use, ask in the chat: “What do I do next to enable every channel?”

1) Clone + configure

From the repo root, create your messages-bridge env file and start the stack.

Commands

cp messages-bridge/.env.example messages-bridge/.env
# edit messages-bridge/.env and add tokens
cd messages-bridge
docker compose up -d --build
What this starts
messages-bridge (port 8787) + toolcall (internal, used by this page’s chat via /api/chat).

2) Verify health

Bridge health endpoints

  • /health should return 200
  • /system-status should show Ollama + bridge status (BlueBubbles omitted in messages-bridge mode)
Tip: if the chat panel says “offline”, the toolcall container isn’t reachable (or Ollama isn’t reachable).

Slack / Telegram / Twilio

  • Slack requires Socket Mode enabled + app installed to the workspace
  • Telegram requires webhook set to /telegram/webhook on this domain
  • Twilio requires the webhook URL(s) you already use (this bridge exposes /twilio)

2.5) Run Cursor on the host (recommended)

If you want the helper chat to be able to do real “Cursor IDE agent” work (edit files, run commands, etc), run the Cursor Runner on the host Mac. Docker will call it via CURSOR_RUNNER_URL.

Start the host runner

# from repo root
python3 -m venv .venv-cursor-runner
source .venv-cursor-runner/bin/activate
pip install -U fastapi uvicorn python-dotenv
export CURSOR_RUNNER_TOKEN='CHANGEME'
python scripts/cursor-runner.py --port 8791
Set the same token in messages-bridge/.env as CURSOR_RUNNER_TOKEN. The container will call http://host.docker.internal:8791/run.
Cursor Runner must run as your logged-in macOS user (so it can use your Cursor login and permissions).

3) Get live help (this page)

Use the chat on the right to ask questions like: “What’s missing from my env?”, “How do I set the Telegram webhook?”, “Why is Slack not connecting?”.

Cursor agent note
This setup chat runs through the local toolcall server via /api/chat. For real host Cursor work, run scripts/cursor-runner.py and set CURSOR_RUNNER_URL/CURSOR_RUNNER_TOKEN.
Page: /p/messages-bridge-setup · Chat: /api/chat
Setup Helper Chat
offline
If chat is offline: confirm Docker is running and toolcall is healthy.