Health Bridge for AI README

Your Apple Health data, continuously available to your own AI agent.

Download on the App Store · Set up your bridge · Supported health data · Website

Apple Health AI Bridge is the open-source project behind Health Bridge for AI.

The project gives you a direct, self-hosted path from Apple Health to the AI tools you choose—without routing it through a hosted intermediary. The iPhone companion continuously sends the HealthKit data you permit to a receiver you control, where read-only CLI and MCP interfaces make it available to compatible agents.

Your health data stays under your control: the receiver and database run on your infrastructure, AI access is read-only, and no hosted relay or third-party model is required.

Automatic background sync is designed for continuous use. iOS controls background scheduling, so delivery timing is best-effort rather than real-time or guaranteed at a specific moment.

Set up the bridge

You need:

• an iPhone running iOS 18 or later;
• a macOS or Linux computer that will run the receiver and store the private database; native Windows is not currently supported;
• for continuous sync, a stable private HTTPS route that the physical iPhone can reach away from the local network; for an explicit local-only evaluation, a same-LAN route with the limitation below;
• an MCP client on the receiver machine, or a terminal for direct CLI access;
• uv for the receiver package.

1. Install the iPhone app

Download Health Bridge for AI from the App Store on your iPhone. TestFlight remains available for beta builds and prerelease testing through the official install page.

2. Prepare the receiver route

The project does not give you a receiver URL. The URL is the private address by which the iPhone reaches your receiver computer, and it must exist before core setup can create pairing material.

• Already use Tailscale: use the private Tailscale Serve HTTPS path documented in the setup guide. Tailscale is an option for existing users, not a product requirement.
• Agent-assisted private HTTPS ingress: use the setup guide's agent-assisted path. The setup agent must inspect first, show every proposed DNS, tunnel, proxy, firewall, and service change, and wait for approval before applying it.
• Local network only: supported as a deliberate local-only fallback, but automatic sync stops when the iPhone leaves that network.

Do not copy a sample hostname, expose receiver port 8765 directly to the public internet, or publish the pairing page. Follow the complete receiver setup guide to produce and verify the real route.

3. Install and run setup

Install the current signed receiver release:

uv tool install "git+https://github.com/roian6/apple-health-ai-bridge.git@receiver-v1.1.1"

The route-specific guide sets HEALTH_BRIDGE_RECEIVER_URL to the exact configured /v1/batches URL. Only then run:

health-bridge setup --receiver-url "$HEALTH_BRIDGE_RECEIVER_URL"

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

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

health-bridge setup creates the private SQLite database and single-use pairing page, prepares the receiver command, emits a canonical same-host stdio MCP descriptor, verifies the local Health Bridge MCP process, and detects client adapters without modifying them.

A successful local MCP check does not prove receiver readiness or phone reachability. Put the printed receiver command under the host's approved service manager, start it, require {"status":"ok"} from the printed local /health URL, and then require the same response from the exact phone-facing /health URL on the physical iPhone. Routes A and B use HTTPS; Route C uses HTTP only on the same trusted LAN.

Adding a client creates another process that can read the private health database, so setup never does that automatically. Use an explicit --configure-client <name> only after choosing the client.

Delivery transports

Direct is the default transport, including direct private HTTPS and trusted-LAN setups. Encrypted iCloud Mailbox is an explicit opt-in, Mac-only Beta; a Direct failure never switches transports automatically.

The Beta applies application-layer encryption and signatures before an envelope reaches the user's iCloud container. The user's Mac receiver decrypts and commits accepted batches, then returns an encrypted, signed ACK; the app advances committed local progress only after validating a committed ACK. The iCloud container and receiver remain user-owned. Mailbox ACK publication also requires the exact signed, notarized macOS helper published with Receiver/CLI 1.1.1; users verify and explicitly install it before the optional per-user LaunchAgent. Follow the mailbox service guide.

4. Pair and sync

1. Continue only after the supervised receiver, local health check, and physical-iPhone health check all pass.
2. On the receiver computer, open the generated pairing HTML on a trusted screen. For a headless receiver, securely copy that one file to a trusted local screen; never publish it or place it on a web server.
3. Scan the QR with iPhone Camera, open the setup link, and connect the companion app.
4. Tap Allow Health Access and review Apple’s native authorization sheet.
5. Enable Automatic Sync.
6. Wait for the first successful receiver upload, then ask your agent about your data.

Example prompts:

• “Show yesterday’s workouts and wake-date sleep.”
• “Which Apple Health metrics have synced recently?”
• “Summarize my last seven days of activity and mark any source or sync gaps.”

What is supported

The companion requests every HealthKit type that is both implemented by the app and available on the current iOS runtime. Unsupported or unavailable types remain absent rather than being fabricated.

See the versioned supported health data reference.

Agent surface

The MCP server is read-only and exposes bounded, source-grounded tools:

• bridge and sync status;
• supported and currently synced metric catalogs;
• time-series observations;
• workouts;
• sleep summaries;
• daily summaries;
• source provenance.

It does not expose raw SQL, token material, cursor values, or clinical recommendations.

Privacy and security

• HealthKit access is read-only.
• The receiver and SQLite database are user-owned.
• The project has no hosted health-data backend.
• Pairing invitations are temporary and single-use.
• Device credentials are stored in the iOS Keychain and hashed at rest by the receiver.
• Logs and agent status omit health values and credentials by default.
• The receiver is designed for one trusted user, not mutually untrusted tenants.
• The developer does not operate or have access to the user's receiver or iCloud container. A “Data Not Collected” App Privacy answer remains valid only while that developer-no-access boundary remains true.

Do not expose the receiver's loopback port or pairing page to the public internet. For continuous sync away from home, use an existing private-network HTTPS route such as Tailscale Serve or an agent-assisted private HTTPS ingress reviewed for the receiver paths. LAN-only access is a limited fallback.

Report vulnerabilities through GitHub’s private vulnerability reporting flow described in SECURITY.md.

Public policies and help: Privacy · Support

Remove local bridge data

Stop the receiver, then inspect the exact deletion scope with the default dry-run:

health-bridge receiver purge --db ~/.local/share/health-bridge/health.sqlite

Run the same command with --confirm only after reviewing the listed database and SQLite sidecars. Confirmation is refused while the receiver is still using the database. This removes the local bridge copy and does not delete Apple Health data. Empty private .lifecycle.lock and .access.lock coordination files and a private .purge-* directory containing zero-byte tomb files may remain; they contain no health records.

If the command returns recovery-required, do not restart the receiver. Review the structured source, quarantine, and truncated path lists; the command deliberately keeps the private quarantine instead of claiming a rollback after an irreversible partial purge.

Component versions and releases

The repository contains independently released components. Always include the component label rather than referring to an unlabeled “repo version.”

These numbers do not need to match. Receiver-only fixes must not force an unchanged iOS Companion update, and compatible product patches must not bump the Batch Protocol. The canonical machine-readable mapping is component-versions.json; see the complete versioning and compatibility policy.

User installs are pinned to a signed Receiver/CLI release tag instead of the moving main branch. Each GitHub Release publishes the exact-tag wheel and source archive together with the signed mailbox helper and its public manifest, SHA-256 checksums, build provenance, and metadata that ties the Receiver/CLI, compatible iOS Companion, helper source tree, Git tree, and Batch Protocol together. Existing v1.0.0, v1.0.1, and receiver-v1.1.0 releases remain immutable; current and future receiver releases use component-scoped tags such as receiver-v1.1.1.

Build from source

The App Store is the normal iPhone installation path. TestFlight is reserved for beta builds. Contributors and advanced users can build with Xcode 16 or later by following docs/self-build.md.

Documentation

• Setup
• Supported health data
• Architecture and trust boundaries
• Brand guide
• Batch contract
• SQLite schema
• Build the iOS app
• Contribution ideas
• Support routes
• Maintainer workflow

Development

uv sync --all-extras --dev --locked
uv run pytest -q
uv run ruff check .
uv run basedpyright

Synthetic fixtures and smoke commands are contributor tools, not part of user onboarding. See CONTRIBUTING.md.

Apple Health AI Bridge is an independent open-source project and is not affiliated with, endorsed by, or sponsored by Apple Inc.

License

Apache-2.0. See LICENSE.