mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-07-02 12:13:05 +00:00
b31b0b9d95
Audited the last 3 releases (v2026.5.28..main) against the docs site and fixed code-vs-docs drift: - slash-commands: add /moa, /prompt, /pet, /hatch, /timestamps - cli-commands: add hermes pets / project / desktop / whatsapp-cloud + dashboard register; correct --insecure (now a deprecated no-op); add gateway migrate-legacy + enroll --wake-url + dashboard --skip-build - environment-variables: document the remaining ~48 env vars (SimpleX, Photon, Teams adapter, per-platform *_ALLOW_ALL_USERS, home-channel vars, IRC, Brave/Krea/Notion/Linear/Airtable/Tenor keys, QQ_SANDBOX) — full OPTIONAL_ENV_VARS (265) now covered - configuration: document tool_loop_guardrails, goals, prompt_caching, network, onboarding, dashboard config blocks - toolsets/tools-reference + tools.md: add coding/project toolsets and read_terminal/project_* tools; remove the stale messaging toolset and send_message agent tool (removed in #47856); drop stale RL-training prose - messaging: new IRC channel page (adapter shipped without docs) + index row + sidebar + env vars - pets: document the /hatch AI generation pipeline + Nous/OpenRouter image backend - web-dashboard: document the bearer-token / TokenPrincipal service auth path - purge agent-callable send_message references across guides/features and the research-paper-writing skill (tool removed in #47856) Verified: docusaurus build succeeds; all authored internal links resolve.
134 lines
5.4 KiB
Markdown
134 lines
5.4 KiB
Markdown
# SimpleX Chat
|
|
|
|
[SimpleX Chat](https://simplex.chat/) is a private, decentralised messaging platform where users own their contacts and groups. Unlike other platforms, SimpleX assigns no persistent user IDs — every contact is identified by an opaque internal ID generated at connection time, which makes it one of the most private messengers available.
|
|
|
|
> Run `hermes gateway setup` and pick **SimpleX** for a guided walk-through.
|
|
|
|
## Prerequisites
|
|
|
|
- The **simplex-chat** CLI installed and running as a daemon
|
|
- Python package **websockets** (`pip install websockets`)
|
|
|
|
## Install simplex-chat
|
|
|
|
Download the latest release from the [simplex-chat GitHub releases](https://github.com/simplex-chat/simplex-chat/releases) page:
|
|
|
|
```bash
|
|
# Linux / macOS binary
|
|
curl -L https://github.com/simplex-chat/simplex-chat/releases/latest/download/simplex-chat-ubuntu-22_04-x86_64 -o simplex-chat
|
|
chmod +x simplex-chat
|
|
```
|
|
|
|
The SimpleX Chat project does not publish a prebuilt Docker image for the chat client; to run it under Docker, build from source from the [simplex-chat repository](https://github.com/simplex-chat/simplex-chat).
|
|
|
|
## Start the daemon
|
|
|
|
```bash
|
|
simplex-chat -p 5225
|
|
```
|
|
|
|
The daemon listens on WebSocket at `ws://127.0.0.1:5225` by default.
|
|
|
|
## Configure Hermes
|
|
|
|
### Via setup wizard
|
|
|
|
```bash
|
|
hermes gateway setup
|
|
```
|
|
|
|
Select **SimpleX Chat** and follow the prompts.
|
|
|
|
### Via environment variables
|
|
|
|
Add these to `~/.hermes/.env`:
|
|
|
|
```
|
|
SIMPLEX_WS_URL=ws://127.0.0.1:5225
|
|
SIMPLEX_ALLOWED_USERS=<contact-id-1>,<contact-id-2>
|
|
SIMPLEX_HOME_CHANNEL=<contact-id>
|
|
```
|
|
|
|
| Variable | Required | Description |
|
|
|---|---|---|
|
|
| `SIMPLEX_WS_URL` | Yes | WebSocket URL of the simplex-chat daemon |
|
|
| `SIMPLEX_ALLOWED_USERS` | Recommended | Comma-separated allowlist. Each entry can be a numeric `contactId` **or** a display name — both forms work. |
|
|
| `SIMPLEX_ALLOW_ALL_USERS` | Optional | Set `true` to allow every contact (use carefully) |
|
|
| `SIMPLEX_AUTO_ACCEPT` | Optional | Auto-accept incoming contact requests (default: `true`) |
|
|
| `SIMPLEX_GROUP_ALLOWED` | Optional | Comma-separated group IDs the bot participates in, or `*` for any group. Omit to ignore group messages entirely |
|
|
| `SIMPLEX_HOME_CHANNEL` | Optional | Default contact/group ID for cron job delivery |
|
|
| `SIMPLEX_HOME_CHANNEL_NAME` | Optional | Human label for the home channel |
|
|
| `HERMES_SIMPLEX_TEXT_BATCH_DELAY` | Optional | Quiet-period seconds (default: `0.8`) used to concatenate rapid-fire inbound text messages into one event |
|
|
|
|
## Find your contact ID or display name
|
|
|
|
After starting the daemon, open a conversation with your agent contact. The numeric `contactId` appears in session logs. If you'd rather use the display name shown in the SimpleX UI, that works too — `SIMPLEX_ALLOWED_USERS` accepts either form.
|
|
|
|
## Authorization
|
|
|
|
By default **all contacts are denied**. You must either:
|
|
|
|
1. Set `SIMPLEX_ALLOWED_USERS` to a comma-separated list of `contactId`s and/or display names (e.g. `SIMPLEX_ALLOWED_USERS=4,alice` matches either contactId 4 or the contact whose display name is "alice"), or
|
|
2. Use **DM pairing** — send any message to the bot and it will reply with a pairing code. Enter that code via `hermes pairing approve simplex <CODE>`.
|
|
|
|
## Group chats
|
|
|
|
By default the adapter ignores group messages — a bot in a group otherwise
|
|
processes every member's traffic. Opt-in explicitly:
|
|
|
|
```
|
|
SIMPLEX_GROUP_ALLOWED=12,34 # specific group IDs
|
|
# or
|
|
SIMPLEX_GROUP_ALLOWED=* # any group the bot is in
|
|
```
|
|
|
|
Address groups by prefixing the chat ID with `group:`, e.g.
|
|
`simplex:group:12` as a cron `deliver=` target or in a `hermes send` call.
|
|
|
|
## Attachments
|
|
|
|
The adapter supports native SimpleX attachments in both directions:
|
|
|
|
- **Inbound** — incoming images, voice notes, and files are accepted via
|
|
the daemon's XFTP flow (`rcvFileDescrReady` → `/freceive` → wait for
|
|
`rcvFileComplete`) and surfaced as `MessageEvent.media_urls` with the
|
|
appropriate `MessageType` (`PHOTO`, `VOICE`, `TEXT` + document).
|
|
- **Outbound** — `send_image_file`, `send_voice`, `send_document`, and
|
|
`send_video` all use the structured `/_send` form with `filePath`, so
|
|
the receiving SimpleX client renders images inline and plays voice
|
|
notes inline rather than offering them as downloads.
|
|
|
|
Agent replies can also embed `MEDIA:/path/to/file` tags in plain text —
|
|
the adapter strips the tag from the body and sends the file as either a
|
|
voice note (audio extensions) or a document.
|
|
|
|
## Using SimpleX with cron jobs
|
|
|
|
```python
|
|
cronjob(
|
|
action="create",
|
|
schedule="every 1h",
|
|
deliver="simplex", # uses SIMPLEX_HOME_CHANNEL
|
|
prompt="Check for alerts and summarise."
|
|
)
|
|
```
|
|
|
|
Or target a specific contact via the cron job's `deliver:` field, or from a shell script with the [`hermes send` CLI](/guides/pipe-script-output):
|
|
|
|
```bash
|
|
hermes send simplex:<contact-id> "Done!"
|
|
```
|
|
|
|
## Privacy notes
|
|
|
|
- SimpleX never reveals phone numbers or email addresses — contacts use opaque IDs
|
|
- The connection between Hermes and the daemon is local WebSocket (`ws://127.0.0.1:5225`) — no data leaves your machine
|
|
- Messages are end-to-end encrypted by the SimpleX protocol before reaching the daemon
|
|
|
|
## Troubleshooting
|
|
|
|
**"Cannot reach daemon"** — Ensure `simplex-chat -p 5225` is running and the port matches `SIMPLEX_WS_URL`.
|
|
|
|
**"websockets not installed"** — Run `pip install websockets`.
|
|
|
|
**Messages not received** — Check that the contact's ID is in `SIMPLEX_ALLOWED_USERS` or approve them via DM pairing.
|