Raft
قناة Raft
What this page is, and what it holds.
This page covers Raft. About 3 minutes to read. Open the channel to yourself first with an allowlist. An open channel means anyone can message your agent.
Connect Hermes Agent to Raft as an external agent via wake-channel bridge
Outcomes taken from this page, not a template.
- Understand what بوابة المراسلة is and when you need it.
- Read the table and take only the row that applies to you.
- Set
RAFT_PROFILEin the right place.
Exactly as they appear in Hermes.
RAFT_PROFILE
Jump to the part you need.
Nothing summarised away.
The documentation body below is reproduced from the official source so commands and identifiers stay exact. Each section carries a short note describing what it contains.
Hermes connects to Raft ↗ as an external agent through a local wake-channel bridge. The adapter starts a loopback HTTP endpoint that receives content-free wake hints from the bridge, then injects them into the Hermes gateway session pipeline. The agent reads and sends messages through the Raft CLI — the adapter never touches message bodies or delivery cursors.
---
Prerequisites
Explains the idea itself. Read it slowly; the later sections build on it.
- A Raft workspace where you can create an External Agent
- The Raft CLI installed and logged in to that External Agent profile
- aiohttp — Python package (included in Hermes
[all]extras)
In Raft, open the Agents menu, create an External Agent, and follow the setup card to install the Raft CLI and log in the agent profile. Once the agent is created, Raft shows a Hermes setup guide with the environment variables and configuration needed to start the gateway.
---
Setup
Ordered, practical steps. Run one and confirm it worked before moving on.
Add to ~/.hermes/.env:
RAFT_PROFILE=your-agent-profileThat's it — the adapter auto-enables when RAFT_PROFILE is set. It generates a per-session bridge token, picks an ephemeral port, and spawns the bridge child process automatically when the gateway starts.
---
How It Works
Explains the idea itself. Read it slowly; the later sections build on it.
Raft Server → Bridge (wake-hints SSE) → POST /wake → Hermes Adapter → Agent context
Agent → raft message check → Raft Server (message bodies)
Agent → raft message send → Raft Server (replies)- The Raft server sends wake hints to the bridge process via SSE.
- The bridge forwards each hint as a
POST /waketo the adapter's loopback endpoint. - The adapter validates the bridge token, verifies the payload is content-free, and injects a wake notice into the Hermes session.
- The agent sees the wake notice and uses the Raft CLI to read messages and reply.
Wake payloads are content-free by contract — they carry metadata (event ID, message ID, timestamps) but never message bodies, channel names, or sender identities. The adapter rejects any payload containing content-shaped fields (text, body, content, messages, etc.).
---
Bridge
Explains the idea itself. Read it slowly; the later sections build on it.
The adapter automatically spawns raft agent bridge as a child process, passing the endpoint URL and token. The bridge connects to the Raft server using the configured profile and begins forwarding wake hints. It is terminated when the gateway shuts down.
---
Environment Variables
Explains the idea itself. Read it slowly; the later sections build on it.
| Variable | Description | Default |
|---|---|---|
RAFT_PROFILE | Raft agent profile slug — auto-enables the adapter when set | _(required)_ |
2 questions answered by this page alone.
Every option is a real identifier from the Hermes documentation. The wrong ones are real too, just from other pages.