snapshot: preserve central wiki state 2026-08-15 (7 modified + 1 new file)

2026-08-15 22:11:30 +08:00
commit 92e8028bb8
71 changed files with 9897 additions and 0 deletions
@@ -0,0 +1,93 @@
+---
+title: Multiplexer Setup (Multi-Profile Gateway)
+type: runbook
+status: active
+created: 2026-07-28
+updated: 2026-07-28
+verified_on: 2026-07-28
+confidence: high
+tags: [hermes, multiplexer, telegram, profiles, gateway]
+---
+
+# Multiplexer Setup
+
+## What It Is
+
+One gateway process serving multiple Hermes profiles through a single Telegram bot. Messages are routed to the correct profile by `profile_routes` (chat_id → profile).
+
+## Architecture
+
+```
+Telegram Bot (single token)
+         │
+         ▼
+   Default Gateway (multiplex_profiles: true)
+         │
+         ├── profile_routes: chat_id → profile
+         │
+         ├── default profile (Rhino chat: -1004321904721)
+         └── ops profile (Tusk ops: -1003914987043, -1003932503629)
+```
+
+## Key Config Locations
+
+### Default profile: `~/.hermes/config.yaml`
+
+```yaml
+gateway:
+  multiplex_profiles: true
+  profile_routes:
+    - name: ops-group
+      platform: telegram
+      chat_id: '-1003914987043'
+      profile: ops
+    - name: ops-group-2
+      platform: telegram
+      chat_id: '-1003932503629'
+      profile: ops
+
+telegram:
+  allowed_chats: '-1004321904721,-1003914987043,-1003932503629'
+  group_allowed_chats: '-1004321904721,-1003914987043,-1003932503629'
+```
+
+### Ops profile: `~/.hermes/profiles/ops/config.yaml`
+
+```yaml
+telegram:
+  allowed_chats:
+    - '-1003914987043'
+    - '-1003932503629'
+  group_allowed_chats:
+    - '-1003914987043'
+    - '-1003932503629'
+
+platforms:
+  telegram:
+    enabled: false   # ← DISABLED — multiplexer handles this
+```
+
+## The Silent-Drop Pitfall
+
+The `allowed_chats` gate runs on the **default profile's adapter** BEFORE `profile_routes` stamps `source.profile`. If a chat is only authorized in the secondary profile's config but not the default's, messages from that chat are silently dropped.
+
+**Moral:** When adding a new chat for a secondary profile, add it to BOTH profiles' `allowed_chats`.
+
+## Adding a New Group
+
+1. Add the chat_id to the default profile's `profile_routes`
+2. Add the chat_id to the ops profile's `allowed_chats` and `group_allowed_chats`
+3. **Add the chat_id to the default profile's `allowed_chats` and `group_allowed_chats`** (comma-separated list)
+4. Restart the gateway: `systemctl --user restart hermes-gateway`
+
+## Restarting
+
+From an SSH shell (outside the agent process):
+```bash
+systemctl --user restart hermes-gateway
+```
+
+## Related
+
+- [[hermes-agent]]
+- [[messaging-integrations]]