Health Bridge for AI
Menu

Install

Start with TestFlight.

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

iOS 18 or later Read-only HealthKit

1. Install the iPhone companion

Open the official Apple TestFlight invitation on your iPhone and install Health Bridge for AI.

Install with TestFlight

2. Choose a route before setup

The receiver URL is not supplied by Health 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 Health 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.1"
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.1, compatible with iPhone Companion 1.1.0 (39) and Batch Protocol 1.0.0.

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 TestFlight 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