Files
agent-estate-wiki/runbooks/multiplexer-setup.md
T

3.7 KiB

title, type, status, created, updated, verified_on, confidence, tags
title type status created updated verified_on confidence tags
Multiplexer Setup (Multi-Profile Gateway) runbook active 2026-07-28 2026-10-20 2026-10-20 high
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

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

telegram:
  allowed_chats:
    - '-1003914987043'
    - '-1003932503629'
  group_allowed_chats:
    - '-1003914987043'
    - '-1003932503629'

platforms:
  telegram:
    enabled: false   # ← DISABLED — multiplexer handles this

⚠ The ops profile was DELETED on 2026-10-11 (verified 2026-10-20)

/home/hermes/.hermes/profiles/ now contains only .deleted/ops (an 8-byte marker file whose entire content is the word deleted, dated 2026-10-11). ~/.hermes/profiles/ops/ no longer exists — there is no config.yaml, no SOUL.md, no profile directory.

But the default profile still routes to it. ~/.hermes/config.yaml still carries both profile_routes entries (ops-group → -1003914987043, ops-group-2 → -1003932503629, both profile: ops), and multiplex_profiles: true is still set. The ops SOUL (Tusk, the African elephant) and its allowed_chats list are gone with the directory.

Consequence: messages arriving in the two ops chats have a route pointing at a profile that no longer exists. Treat the "Ops profile" blocks below as historical — the second profile's config can no longer be read at ~/.hermes/profiles/ops/config.yaml because that path is gone.

Two things need a decision (not actioned here):

  1. Should profile_routes be removed, or should the ops profile be recreated?
  2. Is the multiplex_profiles: true + two-route configuration still needed at all?

Until that is settled, treat the ops chat IDs as possibly unroutable and verify the gateway actually resolves them before relying on this runbook.

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):

systemctl --user restart hermes-gateway