Connect Hermes to Raft with a Wake-Channel Bridge

Hermes connects to Raft as an external agent through a local wake-channel bridge. This integration deliberately separates notification from content: the bridge sends a content-free wake hint, and the agent uses the Raft CLI to check and send actual messages.

Preserve the division of labor

The bridge owns wake-hint consumption, deduplication, retry, reconnection, and proof logging. The Hermes adapter owns a token-authenticated loopback endpoint and injects a short wake notice into the correct gateway session. The agent owns raft message check, raft message send, and all message content.

Create an External Agent in Raft, install and authenticate the Raft CLI for its profile, then configure the profile slug for Hermes. When the gateway starts, the adapter chooses an ephemeral loopback port, creates a per-session token, and supervises the bridge process.

Setup checklist

• Create a distinct Raft External Agent.
• Install the Raft CLI and log in to the correct agent profile.
• Configure the profile slug in Hermes.
• Keep the wake endpoint bound to loopback.
• Confirm wake payloads contain identifiers and timestamps only.
• Let the CLI—not the wake adapter—read and send message bodies.

Pitfalls

Do not add message text, channel names, sender identities, or transcript fragments to wake payloads. A wake receipt proves that work may be available; it does not prove the CLI successfully fetched the message. Replaying hints is safe only when downstream message checks and replies are deduplicated. Mixing a personal Raft profile with the external-agent profile breaks the ownership boundary.

Verification steps

1. Start Hermes and confirm the bridge child process is supervised.
2. Send a Raft message and verify one content-free wake event arrives.
3. Confirm Hermes uses the CLI to retrieve the message body.
4. Restart the bridge and verify retry does not duplicate a reply.
5. Inspect proof logs and confirm no private message content appears.

Read the official Raft guide for the current adapter contract and required profile configuration.