Skip to content
Casaconomy Book

Mobile AI Bridge — Cloud Bridge via Cloudflare Tunnel

Mobile AI Bridge — Cloud Bridge via Cloudflare Tunnel

Status: Delivered
CAS: CAS-2098
Delivered: 2026-05-10
PRs: #549 (Cloudflare Worker), #548 (cloudflared tunnel), #551 (Mac daemon), #550 (iOS provider), #557 (pairing contract + fallback), #559 (iOS PIN entry), #563 (stream/offline gaps)

What’s new

The iOS app can now route AI conversations through the regent’s Claude Max subscription via a Cloudflare tunnel — no API credits required. iOS sends encrypted prompts to a Cloudflare Worker, which forwards them through a named tunnel to a daemon running on the regent’s Mac, which calls the claude CLI and streams responses back to the device. The wire format uses end-to-end AEAD encryption (XChaCha20-Poly1305) so Cloudflare never sees plaintext.

How to use it

One-time setup (Mac side): The casaconomy-ai-bridge daemon is installed as a launchd service on the regent’s Mac (~/Library/LaunchAgents/). It starts automatically on login and holds the cloudflared tunnel open. No manual steps after initial setup.

Pairing (iOS side):

  1. Open Settings → AI Provider on the iOS app.
  2. Select “Cloud Bridge.”
  3. Enter the six-digit PIN displayed on the desktop app’s pairing screen.
  4. The app exchanges keys and stores the shared secret in the iOS Keychain.

Once paired, the iOS app routes all AI requests (bug-report chat, and future AI surfaces) through Cloud Bridge automatically. A banner appears when the Mac is offline, indicating the AI is unavailable rather than failing silently.

What changed under the hood

  • Cloudflare Worker (workers/ai-bridge/) — stateless edge function at ai-bridge.casaconomy.com/v1/chat. Validates bearer auth, proxies encrypted blobs to the cloudflared tunnel. Worker stays opaque to the plaintext.
  • Mac daemon (src-tauri/src/bin/casaconomy-ai-bridge.rs) — Rust binary that decrypts incoming envelopes, dispatches on a command field (ai_chat in v1), spawns claude --output-format stream-json, and SSE-streams the response back. Unknown commands return a structured 400 so future commands are additive with no protocol break.
  • iOS CloudBridgeProvider (src-tauri/src/services/ai/cloudbridge.rs) — AIManager variant that encrypts the command envelope, posts to the Worker, and emits Tauri events as SSE frames arrive. Falls back gracefully when the Mac is unreachable.
  • PIN pairing sheet — iOS presents a six-digit PIN entry sheet (src/pages/) that completes the Diffie-Hellman handshake with the desktop app to establish the shared AEAD key.

Why we built it

The desktop LocalCli provider spawns a claude subprocess directly — that pattern is forbidden in iOS’s sandbox. Rather than fall back to pay-as-you-go API credits (which were depleted), we built a tunnel so mobile can use the regent’s Claude Max plan. The same bridge is the foundation for future chat-driven mobile actions (sync transactions, query queues, rules application) where the AI needs to read or write app state on the regent’s Mac.

Known limitations / follow-on work

  • Cloud Bridge requires the regent’s Mac to be online and the daemon running. AI features on iOS are unavailable when the Mac is off.
  • Pairing is per-device and manual; no push-provisioning for beta testers yet.
  • Only ai_chat command is implemented. Future commands (sync_transactions, etc.) need new handler modules in the Mac daemon but no wire-format changes.
  • Docs for the architecture contract are in docs/architecture/mobile-ai-bridge.md (added in CAS-2105).