# 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