HealthKit summaries

Apus can request a read-only summary of the current calendar day from a connected iPhone or iPad node. The device computes the aggregate on-device and returns only steps, sleep duration, average resting heart rate, and workout count/duration. Individual HealthKit samples, sources, metadata, clinical records, background ingestion, and writes are not supported.

This feature is off by default. It requires separate consent on the iOS device and authorization on the Gateway.

Requirements

• An iPhone or iPad running the Apus iOS app where HealthKit reports health data as available.
• A connected and approved iOS node. See iOS app setup.
• A current Gateway that can reach the iOS node.
• Readable Health data for any metrics you expect to see. An Apple Watch can contribute data to the Apple Health store, but the Apus watchOS app is not required for HealthKit summaries.

Enable access

1. Authorize the Gateway command

Add health.summary to the existing gateway.nodes.commands.allow array in apus.json. Preserve any commands already present:

{
  gateway: {
    nodes: {
      commands: { allow: ["health.summary"] },
    },
  },
}

health.summary is classified as privacy-heavy and is never allowed by the iOS platform default. An entry in gateway.nodes.commands.deny overrides the allow entry. See Node command policy.

2. Enable sharing on the iOS device

In the iOS app:

1. Open Settings -> Permissions and find Apple Health Summaries in the always-visible Apple Health section.
2. Tap Enable Apple Health Summaries.
3. Read the disclosure, then choose which Health categories Apus may read in Apple's permission sheet.

The switch records your explicit Apus sharing choice. It does not claim that Apple granted every requested category.

Enabling Health summaries adds health.summary to the node's declared command surface. Approve the resulting node pairing update:

apus nodes pending
apus nodes approve <requestId>

Then verify that the connected iOS device exposes an effective health.summary command:

apus nodes describe --node "<iOS device name>"

Request today's summary

Only today is supported. It covers local midnight through the request time, using the iOS device's current calendar and time zone.

apus nodes invoke \
  --node "<iOS device name>" \
  --command health.summary \
  --params '{"period":"today"}' \
  --json

Agents can call the same command with the nodes tool:

{
  "action": "invoke",
  "node": "<iOS device name>",
  "invokeCommand": "health.summary",
  "invokeParamsJson": "{\"period\":\"today\"}"
}

The summary payload contains:

Metric fields are optional and are omitted when HealthKit returns no readable value. Sleep stages and overlapping sources are merged before duration is calculated, so the same minute is not counted twice.

Privacy behavior

• Aggregation happens on the iOS device. Raw samples do not leave the device.
• The requested aggregate leaves the device through your Gateway. When an agent requests it, the aggregate reaches the configured AI provider and may remain in chat history. A direct CLI invocation returns it to the CLI operator.
• Apus requests read access only. It cannot add or modify Health data.
• Apus reads HealthKit only when health.summary is invoked. There is no background health ingestion.
• HealthKit deliberately does not reveal whether read access was denied. A missing metric can mean denied access, no matching samples, or an unavailable data type. Apus cannot distinguish those cases.
• The summary is for personal health and fitness context, not diagnosis or medical advice.

To stop sharing, return to Apple Health Summaries and tap Turn Off Summaries. The iOS device then removes the Health capability and health.summary command from its node surface. You can also remove health.summary from gateway.nodes.commands.allow to close the Gateway side of the gate.

Troubleshooting

Command is not declared by the node

Confirm Apple Health summaries are enabled in the iOS app and the device is connected. Run apus nodes pending and approve any capability update, then inspect apus nodes describe --node "<iOS device name>" again.

Command requires explicit opt-in

Add health.summary to gateway.nodes.commands.allow. Also check that gateway.nodes.commands.deny does not contain it; the deny list wins.

HEALTH_ACCESS_DISABLED

The app-side sharing switch is off. Enable Apple Health Summaries under Settings -> Permissions -> Apple Health on the iOS device.

Summary succeeds but metrics are missing

Open Apple's Health app and confirm that data exists for today. Review Apus's access in Apple's Health settings, but do not treat an empty result as proof that access was denied: HealthKit intentionally hides that distinction.

Older ranges fail

The command accepts only {"period":"today"}. Multi-day and historical summaries are not supported.

Related

• iOS app
• Nodes
• Gateway configuration reference
• Security audit