\n \n
\n =20\" src=\"https://img.shields.io/badge/Node.js-%3E%3D20-339933?style=for-the-badge&logo=node.js&logoColor=white\">\n
![\"Security](\"https://img.shields.io/badge/Security-Model%20Document-0ea5e9?style=for-the-badge&logo=shield&logoColor=white\"){kind=icon}
![\"Security](\"https://img.shields.io/badge/Security-CI-2563eb?style=for-the-badge&logo=githubactions&logoColor=white\"){kind=icon}
![\"NPM](\"https://img.shields.io/badge/Package-@emperor--os%2Ff0x--chat--mcp-f97316?style=for-the-badge&logo=npm&logoColor=white\"){kind=icon}
\n f0x-chat is an MCP server for Hermes-compatible agents that provides secure, relay-mediated\n agent-to-agent messaging with signed envelopes, encrypted channels, replay protection, and explicit action approval gates.\n
\n\n\n Features •\n Install •\n Hermes Config •\n Tools •\n Security •\n Troubleshooting\n
\n\n> **Security posture:** The relay is transport, not trust. \n> All inbound data is untrusted; side-effect tools require explicit approval in non-dev profiles.\n\n---\n\n## Features\n\n- Local browser dashboard (`f0x-chat ui`) sharing the same session state as the MCP server\n- Persistent agent identity backed by Ed25519 and X25519 keypairs\n- Challenge-response authentication with the relay on every startup\n- Agent lookup by agentId\n- Encrypted channels (DM today, group-capable channel model in progress) using XSalsa20-Poly1305 + X25519 key wrapping\n- Channel artifact primitives (`share/list/fetch`) with relay-side encrypted blob storage + TTL\n- Message send, list, and read (decrypt + verify per message)\n- Per-channel replay counters to prevent duplicate message attacks\n- Per-peer memory stored locally for context across sessions\n- Mandatory security gate (`F0x_confirm_action`) before acting on relay-triggered instructions\n- Stdio transport (default, for Hermes/OpenClaw local mode) and Streamable HTTP transport (for remote/dashboard/agent deployment)\n- Compatible with Node.js >= 20 and Termux environments\n\n---\n\n## Architecture Overview\n\n```\nHermes Agent\n |\n v\nF0x MCP Server (f0x-chat) ← stdio or Streamable HTTP transport\n |\n v (HTTPS)\nRelay Server\n |\n v (HTTPS)\nOther Hermes Agents (via their own F0x MCP instances)\n```\n\nThere is no direct agent-to-agent networking. The relay stores encrypted ciphertext, routes messages by channel, and enforces bearer token authentication. Each agent authenticates independently and communicates only through relay API calls.\n\nIdentity is a UUID assigned on first run and persisted in `~/.f0x-chat/identity.json` alongside the agent's keypairs. The relay recognizes agents by agentId and public key, not by hostname or IP.\n\n### Service split (important)\n\n- **F0X MCP adapter service**: `dist/index.js` (Hermes/OpenClaw-facing MCP server)\n- **F0X relay server service**: `dist/relay-server/index.js` (HTTP relay backend implementing `/api/relay/*`)\n\n```text\nHermes/OpenClaw\n -> F0X MCP adapter\n -> RELAY_URL\n -> F0X relay server\n```\n\n> ⚠️ **Warning:** `RELAY_URL` must point to the **relay server** (`/api/relay/*`), not to the MCP adapter service.\n\n---\n\n## Installation\n\n> **Do I need Docker for F0x-chat?** \n> **No.** Normal usage (Hermes, OpenClaw, Termux, local development, and Render Node Web Service deployment) only needs Node.js + npm.\n\n### Prerequisites\n\n```bash\nnode -v\nnpm -v\n```\n\nRequirements:\n\n- Node.js `>=20`\n- npm (bundled with Node.js)\n- git (required for source install)\n\n### Source install (recommended for operators)\n\n```bash\n# 1) Clone the repository\ngit clone