“Local-first” should be testable. It should tell you where data originates, which process can read it, what network hop is optional, and where the resulting file lives.
For Health.md, the primary source boundary is the phone. The iPhone reads Apple Health through HealthKit. Android reads Health Connect through the on-device API. The user selects permissions, metrics, dates, and a destination.
The ordinary file path
The simplest workflow has no Health.md health-data server:
- the phone reads an authorized platform API;
- Health.md builds the selected output on-device;
- it writes into a folder the user chose.
That folder may be local, in an Obsidian vault, or exposed by a sync provider. If the user chooses iCloud Drive, Google Drive, OneDrive, Syncthing, or Obsidian Sync, that provider's own network and privacy model applies. “Health.md has no cloud hop” does not mean a user-selected destination cannot sync.
Direct computer access
The standalone CLI pairs with an open iPhone or Android device over Manual IP or Tailscale. Pairing and transport are authenticated and encrypted. The phone still performs the platform health read; the CLI receives the explicitly requested result.
Trust material belongs in the operating system credential service. Large health-bearing bodies go to validated files or a private durable spool rather than being copied automatically into an agent conversation. Job status is designed to expose health-free progress fields such as IDs, counts, bytes, and safe errors.
The Mac path
The Apple apps can also prepare files for a connected Mac over the local network. The Mac is a destination and automation surface, not a replacement HealthKit source. Encrypted context and direct export paths keep version, coverage, and compatibility boundaries explicit.
The bundled Mac MCP server is a production component of the Mac app. The standalone cross-platform CLI/MCP package is versioned and qualified separately; a successful Mac workflow does not certify every Linux, Windows, Android, LAN, or Tailscale combination.
Intentional network destinations
Local-first does not ban networks. It makes remote movement explicit.
The iPhone API Endpoint target POSTs selected JSON to a URL the user configures. Android raw snapshots can be sent to an explicitly selected HTTPS endpoint under stricter redirect and checksum rules. Connected provider features contact the provider the user chose. These are disclosed destinations, not a hidden Health.md relay.
Analytics and billing boundaries
Product analytics must not contain health values, metric names, health dates, exported files, private paths, credentials, or user-entered text. Store purchases are handled by Apple or Google. The F-Droid Android build excludes billing and Health.md telemetry code entirely.
Questions to ask any health-data tool
- Which device or service performs the read?
- Is the requested scope visible before access?
- Where are credentials stored?
- Can the tool distinguish empty from unavailable?
- Does a timeout cancel work or leave an unknown outcome?
- Which cloud or sync provider receives the result?
- Can a user delete trust and exported files independently?
A local-first design is strongest when those answers are part of the public contract, not assumptions left to a privacy-policy summary.