Hermes Agent Kanban Multi-Gateway Deployment Guide
Runs multiple Hermes Agent gateways, one per profile, with a single Kanban dispatcher.
Hermes Agent supports running multiple gateway processes at the same time, one per profile, and this page explains how to wire that multi-gateway setup into the Kanban task system. Once configured, each gateway opens its own connection to platform APIs and delivers messages for its profile's subscribers, while exactly one gateway owns the Kanban dispatcher so that work is never spawned twice.
What It Does
- Runs multiple gateway processes concurrently, one per profile:
default,writer,admin,coder, andresearcherare the profiles named in the official documentation. - Lets each gateway open its own connection to platform APIs and deliver messages for its profile's subscribers.
- Delivers task subscription events, including review feedback. A
changes_requestedreview event is delivered as an actionable review-BLOCK notification. - Supports
notify+wakesubscriptions that wake the exact originating chat, thread, or session so the controller inspects the existing card and current run. - Keeps
notifypassive-only andwakewake-only as distinct subscription modes. - Ensures review feedback never creates, unblocks, requeues, or otherwise mutates a task.
- Enforces a single-dispatcher posture: only one gateway owns the Kanban dispatcher, so multiple gateways do not race to spawn the same work.
- Delivers notifications in a profile-owned way: each gateway polls only subscriptions for profiles whose platform adapters it hosts.
- Uses an atomic event claim to prevent duplicate delivery across watcher processes.
According to the official documentation, the split between dispatching and notification delivery is deliberate. Dispatching is single-owner, which is why only one gateway may have kanban.dispatch_in_gateway: true. Notification delivery, by contrast, is profile-owned: each gateway is responsible for the subscriptions belonging to the profiles whose platform adapters it hosts. The atomic event claim is the mechanism that keeps watcher processes from delivering the same event twice.
Setup
The setup is intentionally small. On the dispatch-owning gateway, typically the default profile, no change is needed. On every other profile gateway, add the following to ~/.hermes/config.yaml:
kanban :
dispatch_in_gateway : false
Alternatively, set the environment variable instead of editing the config file:
HERMES_KANBAN_DISPATCH_IN_GATEWAY=false
That is the entire configuration surface described by the official documentation. The dispatch-owning gateway keeps the default value of true; every other gateway sets it to false.
Step-by-step
- Decide which profile will own the dispatcher. The official documentation states this is typically the
defaultprofile, described as the "confirmed dispatch-lock owner." - Leave the dispatch-owning gateway untouched. It keeps
kanban.dispatch_in_gateway: true, which is the default. - On every other profile gateway (
writer,admin,coder, and any others), edit~/.hermes/config.yamland setkanban.dispatch_in_gatewaytofalse, or exportHERMES_KANBAN_DISPATCH_IN_GATEWAY=falsein that gateway's environment. - Start the gateways. Each one opens its own connection to platform APIs and begins delivering messages for its profile's subscribers.
- Confirm the posture: exactly one gateway should report
dispatch_in_gateway: true, and all others should reportfalse.
Configuration Reference
| Option | Where it lives | What it does | Default |
|---|---|---|---|
kanban.dispatch_in_gateway | ~/.hermes/config.yaml | Determines whether this gateway owns the Kanban dispatcher | true |
HERMES_KANBAN_DISPATCH_IN_GATEWAY | Environment variable | Environment-variable equivalent of the config key above | Not stated in the source |
There are no other options documented in the source material. The config key and the environment variable are the two ways to express the same setting, and the documentation presents them as alternatives rather than as settings that must be combined.
How It Works
The official documentation lays out the division of labor across gateways in a table. The columns are: gateway role, dispatch_in_gateway, whether the gateway opens subscribed board DBs, whether it acts as dispatcher, and whether it acts as notifier.
default(confirmed dispatch-lock owner):dispatch_in_gatewayistrue(the default); it opens subscribed board DBs; it is the dispatcher; and it notifies for owned profiles plus legacy unstamped subscriptions.writer,admin,coder, etc.:dispatch_in_gatewayisfalse; they open subscribed board DBs when the profile has subscriptions; they are not the dispatcher; and they notify for that gateway's owned profiles.
Non-dispatch gateways still deliver messages for their own platform adapters, such as Telegram and Discord. They do not dispatch tasks, and they skip boards that have no subscriptions owned by their profiles.
The reason for the single-owner rule is stated plainly: dispatching is single-owner so multiple gateways do not race to spawn the same work. Notification delivery is profile-owned instead. Each gateway polls only subscriptions for profiles whose platform adapters it hosts, and the atomic event claim prevents duplicate delivery across watcher processes.
Review feedback flow
Task subscriptions also cover review feedback. A changes_requested review event is delivered as an actionable review-BLOCK notification. Subscriptions using notify+wake additionally wake the exact originating chat, thread, or session, so the controller inspects the existing card and current run. The documentation is explicit that notify remains passive-only and wake remains wake-only. Review feedback never creates, unblocks, requeues, or otherwise mutates a task.
Requirements and Limitations
- The documentation names the profiles it supports:
default,writer,admin,coder, andresearcher. It uses "etc." when describing non-dispatch gateways, so additional profiles may exist, but only these are named. - Exactly one gateway may own the dispatcher. Running more than one gateway with
dispatch_in_gateway: truecontradicts the documented single-dispatcher posture. - The dispatch-owning gateway is described as the "confirmed dispatch-lock owner," which implies a lock is involved in confirming ownership, though the source does not describe the lock mechanism itself.
- Non-dispatch gateways skip boards that have no subscriptions owned by their profiles. If a profile owns no subscriptions, that gateway will not open those boards.
- Review feedback is notification-only. It does not create, unblock, requeue, or otherwise mutate a task.
notifyis passive-only andwakeis wake-only. The combinednotify+wakemode is what wakes the originating chat, thread, or session.- The source does not state version numbers, platform support beyond the named adapters, or pricing, so none are asserted here.
Troubleshooting
The source material does not document specific error messages or failure modes, so no error strings are reproduced here. The one failure mode the documentation addresses directly is the race condition it designs against: if more than one gateway dispatches, multiple gateways could race to spawn the same work. The fix the documentation gives is the single-dispatcher posture itself: keep kanban.dispatch_in_gateway: true on exactly one gateway, typically default, and set it to false on every other profile gateway via ~/.hermes/config.yaml or the HERMES_KANBAN_DISPATCH_IN_GATEWAY=false environment variable.
If notifications appear to be missing on a non-dispatch gateway, check whether that gateway's profile actually owns subscriptions. The documentation states that each gateway polls only subscriptions for profiles whose platform adapters it hosts, and that non-dispatch gateways skip boards with no subscriptions owned by their profiles. A gateway with no owned subscriptions on a board will not poll it.
If the same event appears to be delivered twice, the documentation points to the atomic event claim as the mechanism that prevents duplicate delivery across watcher processes. The source does not describe what to do if that claim fails, so no remedy is invented here.
Sources & References
This page was researched from 1 independent source, combined and verified for completeness.
- 1.Kanban Multi-Gateway DeploymentOfficial documentation · primary source
The #1 AI Newsletter
The most important ai updates, guides, and fixes — one weekly email.
No spam, unsubscribe anytime. Privacy policy