Bagas Purwa Sentika
0355858596
Phase 2: memory, session search, git worktree configured Phase 3: Telegram gateway connected, DM pairing approved Phase 4: custom skills created (aws-diagnostics, jira-query, confluence-search, bitbucket-pr)
105 lines
3.2 KiB
Markdown
105 lines
3.2 KiB
Markdown
# Hermes Agent: Gateway System (Messaging)
|
|
|
|
## Platform Support
|
|
|
|
Hermes supports 20+ messaging platforms. Key ones for ngn-agent:
|
|
|
|
| Platform | Voice | Images | Files | Threads | Reactions | Typing | Streaming |
|
|
|----------|-------|--------|-------|---------|-----------|--------|-----------|
|
|
| **Telegram** | ✅ | ✅ | ✅ | ✅ | — | ✅ | ✅ |
|
|
| **Discord** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
| **Slack** | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
| **Microsoft Teams** | — | ✅ | — | ✅ | — | ✅ | — |
|
|
| **Email** | — | ✅ | ✅ | ✅ | — | — | — |
|
|
|
|
## Telegram Setup
|
|
|
|
```bash
|
|
# Interactive wizard
|
|
hermes gateway setup
|
|
|
|
# Or manual:
|
|
# 1. Create bot via @BotFather → get token
|
|
# 2. Set TELEGRAM_BOT_TOKEN in ~/.hermes/.env
|
|
# 3. Set TELEGRAM_ALLOWED_USERS or use DM pairing
|
|
# 4. Start gateway: hermes gateway
|
|
# 5. Register as service: hermes gateway install
|
|
```
|
|
|
|
## Security & User Authorization
|
|
|
|
**Default: deny all.** Every user must be in an allowlist or paired via DM.
|
|
|
|
```yaml
|
|
# Allowlist (recommended for known users)
|
|
TELEGRAM_ALLOWED_USERS=123456789
|
|
|
|
# DM pairing (alternative — users get pairing codes)
|
|
# User DMs bot → gets code "XKGH5N7P"
|
|
# Admin approves: hermes pairing approve telegram XKGH5N7P
|
|
# Code expires 1hr, cryptographic randomness, rate-limited
|
|
|
|
# Admin vs Regular user split
|
|
gateway:
|
|
platforms:
|
|
telegram:
|
|
extra:
|
|
allow_from: ["111", "222"]
|
|
allow_admin_from: ["111"]
|
|
user_allowed_commands: [status, model]
|
|
```
|
|
|
|
## Session Management
|
|
|
|
```yaml
|
|
session_reset:
|
|
mode: both # both | idle | daily | none
|
|
idle_minutes: 1440 # 24 hours
|
|
at_hour: 4 # 4 AM daily
|
|
```
|
|
|
|
Per-platform overrides:
|
|
```json
|
|
{
|
|
"reset_by_platform": {
|
|
"telegram": { "mode": "idle", "idle_minutes": 240 }
|
|
}
|
|
}
|
|
```
|
|
|
|
## Gateway Commands
|
|
|
|
```
|
|
hermes gateway # Run in foreground
|
|
hermes gateway setup # Configure platforms interactively
|
|
hermes gateway install # Install as service (launchd/systemd)
|
|
hermes gateway start/stop/status
|
|
```
|
|
|
|
## Gateway Slash Commands (inside chat)
|
|
|
|
`/new /reset /model /retry /undo /status /stop /approve /deny /sethome`
|
|
`/compress /background /platform /skills /cron /help`
|
|
|
|
## Multi-Platform Operations
|
|
|
|
- `/platform list|pause|resume` — manage individual adapters without restart
|
|
- Automatic circuit breaker — pauses adapter on repeated failures
|
|
- Restart notifications — sends "agent is back" to home channels
|
|
- Session resume across restarts — auto-recovers interrupted sessions
|
|
|
|
## Admin vs Regular Users
|
|
|
|
Two tiers: admin (full access) and user (restricted slash commands). Configured per platform per scope (DM vs group). Use `/whoami` to check your access.
|
|
|
|
## Background Sessions
|
|
|
|
`/background Check all servers` spawns isolated async agent. Results delivered to originating chat when done. Non-blocking — main chat stays interactive.
|
|
|
|
## Key ngn-agent Considerations
|
|
|
|
- **Start with Telegram** — most accessible, mobile-friendly
|
|
- **Use DM pairing** for initial setup, switch to allowlist for stability
|
|
- **Set session_reset.mode: idle** with longer timeout for infra context retention
|
|
- **Background sessions** perfect for `"Check all prod servers"` type commands
|
|
- **Circuit breaker** auto-pauses Telegram if API goes down — monitor gateway logs |