Hermes + Apple Health setup

Connect the native Hermes plugin to selected daily metrics from Apple Health Data AI Analyzer on your Mac, with explicit opt-in and token authentication.

Release status, November 16, 2026: the Hermes marketplace plugin is available. Mac version 2.014, which adds an in-app Hermes setup guide, has been submitted to Apple and is awaiting review. That guide is not yet an App Store release. The plugin uses the existing Local API; you can follow the setup below on a compatible Mac app version without the new guide.

Requirements and installation

The Mac app is a separate product. Installing the free plugin does not unlock paid app features or change the app's subscription requirements.

  1. Prepare your dataset. Open Apple Health Data AI Analyzer on your Mac. Import and analyze an Apple Health export, or follow the iPhone-to-Mac sync guide. In Integrations, select the intended analysis using Use Last Analysis or Use for Integrations, as offered by your app version. Confirm that it includes the date you want.
  2. Enable Local API yourself. Keep the Mac app running. The plugin connects only to http://127.0.0.1:8765. Installing the plugin does not start the app or enable its API.
  3. Install the native plugin. Use the Apple Health Analyzer marketplace listing, or run the repository installation command below in your terminal. Hermes must be version 0.23.1 or later, running directly on the same Mac.
hermes plugins install krumjahn/apple-health-hermes
  1. Set the secret outside chat. In Hermes Desktop, open Settings → Plugins and this plugin. Enter your Mac app local API token into the masked Mac app local API token field, backed by APPLE_HEALTH_ANALYZER_TOKEN. If the app offers only Copy Token Path, retrieve the token yourself and transfer it directly to that secret field. Never paste it into a conversation, prompt, screenshot, or tool argument. The plugin does not find or read token files for you. CLI users should use Hermes's supported profile secret configuration.
  2. Review privacy and opt in. Turn on Allow health summaries in Hermes yourself only if you accept the data flow below. It defaults to off and is separate from enabling the plugin.
  3. Enable the plugin and start a new conversation. Ask Hermes to check Apple Health Analyzer's connection first. Then request one explicit date and only the metric groups you need.

Try a focused question

Check Apple Health Analyzer's connection.
Show only my steps and sleep for 2026-11-01.
If that date is missing, say so instead of substituting another day.

Replace this example date with one present in your own dataset. Connection status returns app identity/version and dataset readiness, not health values. Even status requires the plugin opt-in.

Tools and data limits

apple_health_analyzer_status checks readiness. apple_health_analyzer_daily_metrics returns selected daily groups.

Supported groups are steps, sleep, workouts, heart_rate, and hrv. The daily tool accepts one explicit YYYY-MM-DD date and selected groups. It includes available seven-day baselines and deltas with units. Sleep is in hours, workout duration in minutes, heart rate in beats per minute, and HRV in milliseconds (SDNN).

Missing values remain null, not zero. A baseline does not guarantee seven complete days of measurements. Dates follow the dataset calendar. If the app falls back to a different date, the plugin withholds health values and returns date_unavailable. The plugin does not sync data or fetch a fresh Apple Health export.

These are recorded summaries, not diagnosis or treatment advice. The plugin does not return recovery scores, narrative signals, workout types, sleep times, or unselected metrics.

Privacy, authentication, and revocation

The Mac connection is local; the AI conversation is not necessarily local. Selected results enter Hermes and may be sent to the model provider configured in your profile and retained in chat history. Review provider and retention settings before opting in. Keep the profile private: anyone who can invoke its tools may request your summaries. Do not enable health access in a shared chat or gateway.

The plugin makes read-only requests to the app, temporarily receives its daily summary, and returns only the selected numeric groups to Hermes. It does not directly access HealthKit or iCloud, upload your XML export, or create a health database. This does not mean Hermes or its provider cannot retain the returned results.

To stop future access, turn Allow health summaries in Hermes off. Every call rechecks consent. You can also disable or remove the plugin, remove its secret, or turn off Local API in the Mac app. Revoking access does not erase past conversations or provider copies.

The plugin calls /openclaw/status without a token and /openclaw/daily-brief?date=YYYY-MM-DD with the X-Health-Analyzer-Token header. These endpoint names are reused by the native Hermes adapter; you do not need the OpenClaw skill or the broader MCP server.

Can I run Hermes on a Beelink or remote machine?

This release supports Hermes running directly on the same Mac as the app. A Beelink, remote computer, VPS, or container has its own loopback network; its 127.0.0.1 is not your Mac. The plugin has no configurable remote host or port. A tunnel would be a separate, untested setup, not supported remote access. Do not expose the health API publicly to work around this limitation.

Troubleshooting

  • consent_required: review the notice and opt in yourself if you want access.
  • token_required or unauthorized: check the token in Hermes's secret field. Do not send it to an agent.
  • request_failed: confirm the Mac app is running, Local API is enabled, and Hermes runs directly on the same Mac.
  • dataset_unavailable: select an analyzed integration dataset in the app.
  • date_unavailable: choose a date actually present in the selected dataset.
  • invalid_response: check app/plugin compatibility; do not bypass validation or share raw health responses.

When reporting issues, share versions and error codes, not tokens or health records.

Next steps

Read the Hermes Apple Health guide, inspect the plugin source and README, or explore the local API reference.

Made by VividSites