---
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]]