Documentation v1.2.2

BluePill Cloud Documentation

Complete deployment, Mac relay setup, reverse tunnel, API reference, and troubleshooting playbook.

1. Overview & Architecture

BluePill unifies a fast native desktop client (bluepill, C++20 + Qt6/QML, ~48 MB RSS), a headless macOS relay daemon (bluepill-server, Python 3 stdlib, ~18 MB RSS), and this zero-dependency BluePill Cloud Relay behind Traefik TLS 1.3.

Zero-SIP Gateway Mode (Default)

Reads ~/Library/Messages/chat.db in SQLite WAL mode (<2ms) and sends via AppleScript / osascript without disabling System Integrity Protection (SIP).

IMCore Private API Mode

Optional IMCore bridge enabling native tapbacks, unsend, edit, typing indicators, and background read receipts.

Traefik Direct Relay (Zero Cloudflare Proxy / Zero Ngrok on API & Tunnel): The WebUI (https://bluepill.nertwork.com) runs via Cloudflare → Traefik, while the Direct API and reverse WebSocket tunnel (https://api.bluepill.nertwork.com/t/<slug> and wss://api.bluepill.nertwork.com/tunnel/connect) route directly through Traefik TLS 1.3 with zero Cloudflare proxy/tunnel dependency.

2. Quickstart

Three ways to test or connect in under 60 seconds:

  1. Try in Browser: Open /demo — zero account needed. Chat with Morpheus, trigger 2FA OTP extraction, and switch between Liquid Glass, Matrix, and Light themes.
  2. Connect Desktop Client to Demo: Open bluepill → Ctrl+, → set Server URL to https://api.bluepill.nertwork.com/demo and Password to demo.
  3. Connect to Your Hosted Relay: Sign in at /portal to copy your personal https://api.bluepill.nertwork.com/t/<slug> endpoint URL and Relay API Password.
Arch Linux / Omarchy Client
yay -S bluepill
bluepill --webui   # Or run 'bluepill' for the native Qt6 GUI

3. macOS Server Setup (bluepill-server)

Run on any Mac signed into your Apple ID in Messages.app (macOS Ventura 13, Sonoma 14, Sequoia 15, Tahoe 26).

Homebrew Install & Preflight
brew tap nertwork/tap
brew install nertwork/tap/bluepill
bluepill-server init
bluepill-server preflight
brew services start bluepill
  • Full Disk Access (FDA): System Settings → Privacy & Security → Full Disk Access → enable Terminal, iTerm2, and Homebrew python3 so chat.db, NoteStore.sqlite, Calendar.sqlitedb, and Photos.sqlite are readable.
  • Automation Permissions: Allow python3 / Terminal to control Messages.app and System Events.
  • Sleep Prevention: Keep an always-on Mac mini / MacBook awake with sudo pmset -a sleep 0 displaysleep 10 autorestart 1 or run caffeinate -s bluepill-server serve.

4. Cloud Relay Tunnel Setup (bluepill-tunnel.py)

No port forwarding, no static residential IP, and no Cloudflare Tunnel or Ngrok required. bluepill-tunnel.py uses 100% Python 3.9+ standard library (ssl, socket, urllib.request) to hold an outbound direct-Traefik TLS WebSocket connection to wss://api.bluepill.nertwork.com/tunnel/connect and proxy requests to http://127.0.0.1:1235.

Download & Run Tunnel
curl -sSL https://bluepill.nertwork.com/downloads/bluepill-tunnel.py -o ~/bin/bluepill-tunnel.py
chmod +x ~/bin/bluepill-tunnel.py
python3 ~/bin/bluepill-tunnel.py \
  --url wss://api.bluepill.nertwork.com/tunnel/connect \
  --token YOUR_TUNNEL_TOKEN \
  --local http://127.0.0.1:1235
~/Library/LaunchAgents/com.nertwork.bluepill-tunnel.plist (Auto-Start)
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.nertwork.bluepill-tunnel</string>
  <key>ProgramArguments</key>
  <array>
    <string>/usr/bin/caffeinate</string>
    <string>-s</string>
    <string>/opt/homebrew/bin/python3</string>
    <string>/Users/YOUR_USER/bin/bluepill-tunnel.py</string>
    <string>--url</string><string>wss://api.bluepill.nertwork.com/tunnel/connect</string>
    <string>--token</string><string>YOUR_TUNNEL_TOKEN</string>
    <string>--local</string><string>http://127.0.0.1:1235</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
  <key>StandardOutPath</key><string>/tmp/bluepill-tunnel.log</string>
  <key>StandardErrorPath</key><string>/tmp/bluepill-tunnel.err.log</string>
</dict>
</plist>

5. Hosted Single-User macOS VM Guide

Dedicated Hosted Mac VMs run on genuine Apple Silicon hardware (Mac mini / Mac Studio) using macOS Sequoia 15+ Virtualization.framework (tart / lume), honoring Apple's 2-VM-per-Mac hardware license and genuine Apple Secure Enclave / Apple ID iMessage registration.

Apple Silicon Host (macOS Sequoia 15+)
brew install cirruslabs/cli/tart
tart clone ghcr.io/cirruslabs/macos-sequoia-base:latest bp-tenant-01
tart set bp-tenant-01 --cpu 4 --memory 8192
tart run bp-tenant-01

Note: Apple Silicon macOS guests cannot be virtualized inside Linux KVM due to Apple SoC ADT/Secure Enclave validation. Linux x86_64 nodes host the BluePill Cloud control plane and Traefik ingress while Apple Silicon nodes execute isolated single-tenant macOS VMs.

6. BlueBubbles 1.9.x & BluePill REST API Reference

Authenticate with query parameter ?password=<relay_password>, header X-BlueBubbles-Auth: <pw>, or Authorization: Bearer <pw>. Base path is /demo (for demo) or /t/<slug> (for tenants).

MethodEndpointPurpose
GET/api/v1/pingHealth check ({"status":200,"data":"pong"})
GET/api/v1/server/infoBluePill server version & capabilities
POST/api/v1/chat/queryList chats with lastMessage & participants
POST/api/v1/message/queryFetch messages for a chatGuid
POST/api/v1/message/textSend text iMessage or SMS
POST/api/v1/message/reactSend tapback (love, like, dislike, laugh, emphasize, question)
POST/api/v1/chat/newCreate a new conversation
GET/api/v1/message/searchSearch messages by query
GET/api/v1/contactList synced AddressBook contacts
GET/POST/api/v1/icloud/{notes,events,photos,calendars,preflight}iCloud Hub modules
cURL Examples (Direct Traefik API: https://api.bluepill.nertwork.com)
curl -s "https://api.bluepill.nertwork.com/demo/api/v1/ping?password=demo"
curl -s -X POST "https://api.bluepill.nertwork.com/demo/api/v1/message/text" \
  -H "X-BlueBubbles-Auth: demo" -H "Content-Type: application/json" \
  -d '{"chatGuid":"iMessage;-;morpheus@nebuchadnezzar.io","message":"help","method":"apple-script"}'

7. Security & Privacy

  • Zero-Knowledge Relay: BluePill Cloud streams HTTP/JSON payloads between your client and Mac in memory. Message contents, attachments, and contacts are never written to disk or SQLite.
  • Metadata-Only Diagnostics: proxy_logs records only HTTP method, stripped path (query passwords removed), HTTP status code, and latency milliseconds.
  • TLS 1.3 via Traefik: Public traffic uses Let's Encrypt TLS certificates with HSTS, HttpOnly/SameSite=Lax HMAC-signed session cookies, and PBKDF2-HMAC-SHA256 (600,000 iterations) credential hashing.

8. Troubleshooting & Stuck-User Checklist

Symptom / CodeRoot CauseFix
502 Bad Gateway Mac bluepill-tunnel.py disconnected or bluepill-server stopped Run bluepill-server doctor on Mac, verify port 1235, restart LaunchAgent.
401 Unauthorized Relay API Password mismatch Copy or rotate Relay Password in /portal (or Admin Support Drawer).
Empty Chats / chat.db denied macOS Full Disk Access not granted Grant FDA to Terminal & Homebrew Python, then run bluepill-server preflight.
Outbound messages fail Messages.app signed out or Automation denied Sign into Apple ID in Messages.app; allow Automation for Messages & System Events.

9. Client Distribution Roadmap

  • Shipped Arch Linux / Omarchy: yay -S bluepill (x86_64 & aarch64) + AppImage.
  • Shipped macOS Server Daemon: brew install nertwork/tap/bluepill.
  • Live BluePill Web Client: Available at /demo and /t/<slug>/web.
  • Active Dev Windows (.exe / .msi) & Debian/Fedora (.deb / .rpm): Cross-compiled Qt6/C++20 Windows installer with Credential Manager & WinRT toast notifications.