0c4cff352a
- website/docs/user-guide/messaging/signal.md: Full setup guide with prerequisites, step-by-step instructions, access policies, features, troubleshooting, security notes, and env var reference - website/docs/user-guide/messaging/index.md: Added Signal to architecture diagram, platform toolset table, security examples, and Next Steps links - website/docs/reference/environment-variables.md: All 7 SIGNAL_* env vars - README.md: Signal in feature table and documentation table - AGENTS.md: Signal in gateway description and env var config section
213 lines
8.4 KiB
Markdown
213 lines
8.4 KiB
Markdown
---
|
|
sidebar_position: 1
|
|
title: "Messaging Gateway"
|
|
description: "Chat with Hermes from Telegram, Discord, Slack, WhatsApp, or Signal — architecture and setup overview"
|
|
---
|
|
|
|
# Messaging Gateway
|
|
|
|
Chat with Hermes from Telegram, Discord, Slack, WhatsApp, or Signal. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.
|
|
|
|
## Architecture
|
|
|
|
```text
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Hermes Gateway │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
|
|
│ │ Telegram │ │ Discord │ │ WhatsApp │ │ Slack │ │ Signal │ │
|
|
│ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter │ │ Adapter│ │
|
|
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │
|
|
│ │ │ │ │ │ │
|
|
│ └─────────────┼────────────┼─────────────┼───────────┘ │
|
|
│ │ │
|
|
│ ┌────────▼────────┐ │
|
|
│ │ Session Store │ │
|
|
│ │ (per-chat) │ │
|
|
│ └────────┬────────┘ │
|
|
│ │ │
|
|
│ ┌────────▼────────┐ │
|
|
│ │ AIAgent │ │
|
|
│ │ (run_agent) │ │
|
|
│ └─────────────────┘ │
|
|
│ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
Each platform adapter receives messages, routes them through a per-chat session store, and dispatches them to the AIAgent for processing. The gateway also runs the cron scheduler, ticking every 60 seconds to execute any due jobs.
|
|
|
|
## Quick Setup
|
|
|
|
The easiest way to configure messaging platforms is the interactive wizard:
|
|
|
|
```bash
|
|
hermes gateway setup # Interactive setup for all messaging platforms
|
|
```
|
|
|
|
This walks you through configuring each platform with arrow-key selection, shows which platforms are already configured, and offers to start/restart the gateway when done.
|
|
|
|
## Gateway Commands
|
|
|
|
```bash
|
|
hermes gateway # Run in foreground
|
|
hermes gateway setup # Configure messaging platforms interactively
|
|
hermes gateway install # Install as systemd service (Linux) / launchd (macOS)
|
|
hermes gateway start # Start the service
|
|
hermes gateway stop # Stop the service
|
|
hermes gateway status # Check service status
|
|
```
|
|
|
|
## Chat Commands (Inside Messaging)
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/new` or `/reset` | Start fresh conversation |
|
|
| `/model [provider:model]` | Show or change the model (supports `provider:model` syntax) |
|
|
| `/provider` | Show available providers with auth status |
|
|
| `/personality [name]` | Set a personality |
|
|
| `/retry` | Retry the last message |
|
|
| `/undo` | Remove the last exchange |
|
|
| `/status` | Show session info |
|
|
| `/stop` | Stop the running agent |
|
|
| `/sethome` | Set this chat as the home channel |
|
|
| `/compress` | Manually compress conversation context |
|
|
| `/usage` | Show token usage for this session |
|
|
| `/insights [days]` | Show usage insights and analytics |
|
|
| `/reload-mcp` | Reload MCP servers from config |
|
|
| `/update` | Update Hermes Agent to the latest version |
|
|
| `/help` | Show available commands |
|
|
| `/<skill-name>` | Invoke any installed skill |
|
|
|
|
## Session Management
|
|
|
|
### Session Persistence
|
|
|
|
Sessions persist across messages until they reset. The agent remembers your conversation context.
|
|
|
|
### Reset Policies
|
|
|
|
Sessions reset based on configurable policies:
|
|
|
|
| Policy | Default | Description |
|
|
|--------|---------|-------------|
|
|
| Daily | 4:00 AM | Reset at a specific hour each day |
|
|
| Idle | 120 min | Reset after N minutes of inactivity |
|
|
| Both | (combined) | Whichever triggers first |
|
|
|
|
Configure per-platform overrides in `~/.hermes/gateway.json`:
|
|
|
|
```json
|
|
{
|
|
"reset_by_platform": {
|
|
"telegram": { "mode": "idle", "idle_minutes": 240 },
|
|
"discord": { "mode": "idle", "idle_minutes": 60 }
|
|
}
|
|
}
|
|
```
|
|
|
|
## Security
|
|
|
|
**By default, the gateway denies all users who are not in an allowlist or paired via DM.** This is the safe default for a bot with terminal access.
|
|
|
|
```bash
|
|
# Restrict to specific users (recommended):
|
|
TELEGRAM_ALLOWED_USERS=123456789,987654321
|
|
DISCORD_ALLOWED_USERS=123456789012345678
|
|
SIGNAL_ALLOWED_USERS=+15551234567,+15559876543
|
|
|
|
# Or allow specific users across all platforms (comma-separated user IDs):
|
|
GATEWAY_ALLOWED_USERS=123456789,987654321
|
|
|
|
# Or explicitly allow all users (NOT recommended for bots with terminal access):
|
|
GATEWAY_ALLOW_ALL_USERS=true
|
|
```
|
|
|
|
### DM Pairing (Alternative to Allowlists)
|
|
|
|
Instead of manually configuring user IDs, unknown users receive a one-time pairing code when they DM the bot:
|
|
|
|
```bash
|
|
# The user sees: "Pairing code: XKGH5N7P"
|
|
# You approve them with:
|
|
hermes pairing approve telegram XKGH5N7P
|
|
|
|
# Other pairing commands:
|
|
hermes pairing list # View pending + approved users
|
|
hermes pairing revoke telegram 123456789 # Remove access
|
|
```
|
|
|
|
Pairing codes expire after 1 hour, are rate-limited, and use cryptographic randomness.
|
|
|
|
## Interrupting the Agent
|
|
|
|
Send any message while the agent is working to interrupt it. Key behaviors:
|
|
|
|
- **In-progress terminal commands are killed immediately** (SIGTERM, then SIGKILL after 1s)
|
|
- **Tool calls are cancelled** — only the currently-executing one runs, the rest are skipped
|
|
- **Multiple messages are combined** — messages sent during interruption are joined into one prompt
|
|
- **`/stop` command** — interrupts without queuing a follow-up message
|
|
|
|
## Tool Progress Notifications
|
|
|
|
Control how much tool activity is displayed in `~/.hermes/config.yaml`:
|
|
|
|
```yaml
|
|
display:
|
|
tool_progress: all # off | new | all | verbose
|
|
```
|
|
|
|
When enabled, the bot sends status messages as it works:
|
|
|
|
```text
|
|
💻 `ls -la`...
|
|
🔍 web_search...
|
|
📄 web_extract...
|
|
🐍 execute_code...
|
|
```
|
|
|
|
## Service Management
|
|
|
|
### Linux (systemd)
|
|
|
|
```bash
|
|
hermes gateway install # Install as user service
|
|
systemctl --user start hermes-gateway
|
|
systemctl --user stop hermes-gateway
|
|
systemctl --user status hermes-gateway
|
|
journalctl --user -u hermes-gateway -f
|
|
|
|
# Enable lingering (keeps running after logout)
|
|
sudo loginctl enable-linger $USER
|
|
```
|
|
|
|
### macOS (launchd)
|
|
|
|
```bash
|
|
hermes gateway install
|
|
launchctl start ai.hermes.gateway
|
|
launchctl stop ai.hermes.gateway
|
|
tail -f ~/.hermes/logs/gateway.log
|
|
```
|
|
|
|
## Platform-Specific Toolsets
|
|
|
|
Each platform has its own toolset:
|
|
|
|
| Platform | Toolset | Capabilities |
|
|
|----------|---------|--------------|
|
|
| CLI | `hermes-cli` | Full access |
|
|
| Telegram | `hermes-telegram` | Full tools including terminal |
|
|
| Discord | `hermes-discord` | Full tools including terminal |
|
|
| WhatsApp | `hermes-whatsapp` | Full tools including terminal |
|
|
| Slack | `hermes-slack` | Full tools including terminal |
|
|
| Signal | `hermes-signal` | Full tools including terminal |
|
|
|
|
## Next Steps
|
|
|
|
- [Telegram Setup](telegram.md)
|
|
- [Discord Setup](discord.md)
|
|
- [Slack Setup](slack.md)
|
|
- [WhatsApp Setup](whatsapp.md)
|
|
- [Signal Setup](signal.md)
|