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.
Reads ~/Library/Messages/chat.db in SQLite WAL mode (<2ms) and sends via AppleScript / osascript without disabling System Integrity Protection (SIP).
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:
- Try in Browser: Open /demo — zero account needed. Chat with Morpheus, trigger 2FA OTP extraction, and switch between Liquid Glass, Matrix, and Light themes.
- Connect Desktop Client to Demo: Open
bluepill→Ctrl+,→ set Server URL tohttps://api.bluepill.nertwork.com/demoand Password todemo. - 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.
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).
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
python3sochat.db,NoteStore.sqlite,Calendar.sqlitedb, andPhotos.sqliteare readable. - Automation Permissions: Allow
python3/ Terminal to controlMessages.appandSystem Events. - Sleep Prevention: Keep an always-on Mac mini / MacBook awake with
sudo pmset -a sleep 0 displaysleep 10 autorestart 1or runcaffeinate -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.
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
<?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.
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).
| Method | Endpoint | Purpose |
|---|---|---|
| GET | /api/v1/ping | Health check ({"status":200,"data":"pong"}) |
| GET | /api/v1/server/info | BluePill server version & capabilities |
| POST | /api/v1/chat/query | List chats with lastMessage & participants |
| POST | /api/v1/message/query | Fetch messages for a chatGuid |
| POST | /api/v1/message/text | Send text iMessage or SMS |
| POST | /api/v1/message/react | Send tapback (love, like, dislike, laugh, emphasize, question) |
| POST | /api/v1/chat/new | Create a new conversation |
| GET | /api/v1/message/search | Search messages by query |
| GET | /api/v1/contact | List synced AddressBook contacts |
| GET/POST | /api/v1/icloud/{notes,events,photos,calendars,preflight} | iCloud Hub modules |
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;-;[email protected]","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_logsrecords 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=LaxHMAC-signed session cookies, and PBKDF2-HMAC-SHA256 (600,000 iterations) credential hashing.
8. Troubleshooting & Stuck-User Checklist
| Symptom / Code | Root Cause | Fix |
|---|---|---|
| 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.