Apple Health AI Bridge

Start with the App Store.

The default path installs the iPhone companion without Xcode, then pairs it with the machine running your receiver and MCP client.

1. Install the iPhone companion

Download the iPhone app from the App Store. TestFlight remains available for beta builds and prerelease testing.

Download on the App Store Join the TestFlight beta

2. Choose a route before setup

The receiver URL is not supplied by Apple Health AI Bridge. It is the private HTTPS route the physical iPhone uses to reach the receiver computer, including when the phone is away from home.

Already use Tailscale?

Use the documented Tailscale Serve route when both the receiver and iPhone are already in the same tailnet. Tailscale is optional, not a product requirement.

Agent-assisted private HTTPS ingress

Use the setup guide's agent-assisted path. The setup agent must inspect first, preview every DNS, tunnel, proxy, firewall, and service change, and wait for approval.

Not a continuous-sync default: A local-network-only route stops syncing when the iPhone leaves that network. Do not copy a sample hostname or expose receiver port 8765 directly to the public internet.

Optional on Mac: Encrypted iCloud Mailbox (Beta) sends encrypted sync files through your own iCloud account. Direct remains the default, and Apple Health AI Bridge never switches between the two methods automatically. Linux receivers use Direct.

3. Install and run setup

BASE="https://github.com"
OWNER="roian6"
REPO="apple-health-ai-bridge"
TAG="@receiver-v1.1.2"
URL="git+$BASE/$OWNER/"
URL="${URL}${REPO}.git${TAG}"
uv tool install "$URL"

# Routes A/B: run only after
# the guide sets the HTTPS URL.
health-bridge setup \
 --receiver-url \
 "$HEALTH_BRIDGE_RECEIVER_URL"

This installs Receiver/CLI 1.1.2, compatible with iPhone Companion 1.1.1 (50) and Batch Protocol 1.0.0.

The receiver can remain running while your AI reads synced data through the CLI or MCP.

For the deliberate Route C local-network-only fallback, use the real LAN URL and its required non-loopback bind instead:

health-bridge setup \
 --receiver-url \
 "$HEALTH_BRIDGE_RECEIVER_URL" \
 --receiver-host 0.0.0.0 \
 --receiver-port 8765

The version-pinned route guide explains how to configure the real URL for each route. Core setup creates the private receiver database and single-use pairing page, emits a same-host stdio MCP descriptor, and verifies the local MCP process. It does not prove receiver readiness or iPhone reachability. Setup does not modify client configuration unless you explicitly choose a client.

4. Supervise, verify, pair, and enable sync

1. Put the command printed by setup under the host's approved service manager, then start the receiver.
2. Require {"status":"ok"} from the printed local /health URL on the receiver host.
3. Open the exact phone-facing /health URL on the physical iPhone and require the same response. Routes A and B use HTTPS; Route C uses HTTP only on the same trusted LAN.
4. Open the private pairing page on the receiver computer and scan its QR with iPhone Camera.
5. Connect the iPhone app and review Apple’s native permission sheet.
6. Enable Automatic Sync and wait for the first successful receiver upload.

Health access stays read-only, and you can change Apple Health permissions at any time in iOS Settings.

Build from source

Contributors and advanced users can follow the versioned self-build guide.

Read setup guide View source