How to connect Apple Health to Hermes

What do you get?

Hermes can use a local Syncky shell skill to read selected Apple Health data and request permitted write-back with source and undo. Free during launch; plans are coming later. See launch access and pricing.

Client health-data envelopes are sealed end to end. Relay sees delivery metadata and plaintext hub notices, but no health values. The local agent keeps plaintext JSON in its inbox; your chosen model sees what the agent supplies. iOS decides background timing and Health reads need an unlocked iPhone. Data can be hours old and writes wait for sync; undelivered envelopes leave Relay on acknowledgment or expiry, at most 7 days.

What do you need before setup?

Use a local Hermes installation with terminal access on a machine you control, a POSIX shell and Node.js 22.15 or newer. Relay operations need outbound HTTPS to the matching relay. Choose your data and model deliberately; agent setup explains relay selection for your app build.

Hermes's official skills documentation describes user skills under ~/.hermes/skills/, with a required SKILL.md in each skill directory. Its environment reference defines HERMES_HOME as the configuration and user-data home. This recipe targets local POSIX use: when using another profile, set HERMES_HOME to that profile's actual home before copying. Separately, keep the same SYNCKY_AGENT_HOME for Syncky setup, the skill and the receiver; its default is ~/.syncky-agent.

How do you set up Hermes?

Download syncky-agent-skills.tar.gz and SHA256SUMS from the matching Syncky release. Verify the archive's SHA-256 against that list before extracting. A checksum detects damage, not a compromised release; release availability is a prerequisite.
From the download directory, copy the complete carried skill:
```
tar -xzf syncky-agent-skills.tar.gz &&
mkdir -p "${HERMES_HOME:-$HOME/.hermes}/skills/syncky" &&
cp -R ./agent-skills/skills/syncky/. "${HERMES_HOME:-$HOME/.hermes}/skills/syncky/"
```
Keep SKILL.md, syncky-agent, syncky-agent.mjs, syncky-agent.mjs.sha256, LICENSE, NOTICE and THIRD-PARTY-NOTICES together. Read the installed instructions and review the package before loading it. The installed syncky-agent launcher in that same skill directory verifies its adjacent bundle's pinned SHA-256; it needs Node.js and a POSIX shell, with no npm at runtime. Resolve its absolute path from the installed directory, including spaces.
Start a new local Hermes session using that same Hermes home. Installed skills are available as slash commands; load /syncky if needed, then request: Use Syncky and start onboarding with a QR code. The carried skill runs selftest, initializes only a fresh Syncky home and produces a private QR/code. Reuse an existing home. A reachable relay and any required invite must already be available; keep invites, QR credentials and home files out of chat and logs.
Scan in Syncky Health and pick the displayed code on the iPhone. Select read types, allowed write types and Health permissions. Scanning alone does not confirm trust: let an existing receiver collect the proof, or ask the skill to wait for it once with the installed launcher after the code pick when no receiver is running.
Choose ongoing receiving or on-demand collection explicitly. Keep one receiver per home and reuse it. The carried launcher supports both receiving modes. Installing the skill does not start a receiver; services and schedules require your explicit request. Without continuous receiving, uploads wait for the next collection and the app can report a missed check-in.
Run the scope-only request below before reading selected data.

What can Hermes read and write?

The shell skill uses the agent's commands: status for pairing and scope, inbox for what the iPhone sent, send for messages to the iPhone and ack to mark inbox entries as handled. It does not require MCP. The agent keeps what the iPhone sent as daily JSON files in its home (inbox/), prunes them after 30 days, and keeps the last 100 send receipts. There is no database and no built-in summaries: your AI agent reads the files it needs. For a host with local MCP support, the conditional alternative is npx -y @syncky/agent mcp, or checksum-verified syncky-health.mcpb imported into a compatible client; Node.js is still required. These alternatives neither pair nor start a receiver.

Every write to Apple Health, every sync report request and every request for more Health types is a message the agent sends to the iPhone. Writes apply only to the types the owner allowed for writing in the app; a sync report or more Health types need the owner's tap on the phone. The signed skill carries the exact formats and limits.

Write only owner-requested entries or entries covered by explicit standing approval. A write is applied only when its type is in the app's write allowance, within the agent's write scope, and authorized by HealthKit (iOS write permission). Written entries identify the requesting agent as their source. A queued or sent write is not an applied write: read the phone's result in the inbox after sync with the carried launcher. To undo, use the iPhone's remove-written-entries control or have the agent send a delete command for its own entry. Follow the operator security rules.

How do you test the connection?

After onboarding, ask: Use Syncky to check the paired iPhone and its read/write scope. Do not read sample values or write anything. The carried skill uses its installed launcher for status. Expect a confirmed iPhone and its last reported sharing/write scope. CLI status reads local state without contacting Relay; it does not establish fresh or complete sample delivery. An empty result is not a measured zero.

How do you troubleshoot this setup?

Skill missing: check that SKILL.md is directly inside the active Hermes home's skills/syncky directory. A different profile can use a different home. Start a new session after copying. The official skills page documents /reload-skills for refreshing slash commands; do not assume it replaces the current conversation's system prompt immediately.
Launcher fails: provide Node.js 22.15 or newer and a POSIX shell in the local terminal environment. Verify the archive and recopy the whole directory; do not edit the pinned digest.
Wrong home or relay: use the same paired Syncky home and saved relay for skill and receiver. HERMES_HOME selects Hermes files, not the Syncky agent home. Do not initialize over existing state.
Unconfirmed phone: pick the code on the iPhone and let the receiver collect its proof, or ask the skill to wait for it once if no receiver is running.
Stale data: check receiving, unlock the phone, review selected categories and Health access, then sync in the app. iOS decides background timing.

What are the frequently asked questions?

Can I copy only SKILL.md into Hermes?

The carried instructions need their adjacent launcher, bundle, digest and notices. Copy the complete folder above. The repository's npm skill is a different distribution and needs npm; see the public installation guide.

Does this require a Hermes MCP configuration?

This guide uses Hermes's shell-skill route. No Hermes MCP configuration is needed for it. A local Hermes terminal must be able to run the installed launcher and access the paired home; remote sandboxes need their own deliberately configured access.

Who sees the data read through the skill?

The local agent decrypts selected data and your model sees what the skill supplies. Protect local storage and choose the model accordingly. Review Privacy and the public security policy.

Agent setup · MCP comparison · All guides · Gemini CLI.

Can the skill ask for additional access?

Only with your explicit approval: the agent sends an access request with the carried launcher's send, naming the read and write types it needs and an optional plain-text reason. A queued request grants nothing: the owner confirms each type on the phone, the reply arrives in the inbox and the next ordinary sync confirms the new scope. This approval is separate from permission to write Health values. Follow access request guidance.