There are two ways to add a platform to the Hermes gateway:
Create a plugin directory in ~/.hermes/plugins/ (or under plugins/platforms/
for bundled plugins) with a plugin.yaml and adapter.py. The adapter
inherits from BasePlatformAdapter and registers via
ctx.register_platform() in the register(ctx) entry point. This requires
zero changes to core Hermes code.
The plugin system automatically handles: adapter creation, config parsing, user authorization, cron delivery, send_message routing, system prompt hints, status display, gateway setup, and more.
Optional hooks cover the edges most adapters need:
env_enablement_fn: () -> Optional[dict] — seeds PlatformConfig.extra
(and an optional home_channel dict) from env vars BEFORE the adapter is
constructed. Without this, env-only setups don't surface in
hermes gateway status or get_connected_platforms() until the SDK
instantiates. Build it from a (ENV_VAR, extra_key, conv) table with
gateway.platforms._shared.seed_extra_from_env(spec, home_env=...); every
read goes through _shared.get_scoped_secret (multiplex-safe, never
os.getenv).apply_yaml_config_fn: (yaml_cfg, platform_cfg) -> Optional[dict] —
translate this platform's config.yaml keys into env vars and seed
PlatformConfig.extra. Lets a plugin own its YAML schema instead of
growing core gateway/config.py boilerplate per platform. Declare a
(yaml_key, ENV_VAR, kind) table and return
_shared.apply_yaml_bridge(platform_cfg, TABLE): it writes env only when
unset (env > YAML), never under a multiplexed secondary profile's scope,
and returns the same values for extra (read extra first in the adapter
via _shared.extra_or_secret). Called during load_gateway_config()
after the generic shared-key loop and before _apply_env_overrides().is_connected: (config) -> bool — for env-only platforms use
_shared.env_is_connected("YOUR_TOKEN_VAR", ...) instead of a hand-rolled
get_env_value check.cron_deliver_env_var: str — name of the *_HOME_CHANNEL env var. When
set, deliver=<name> cron jobs route to this var without editing
cron/scheduler.py's hardcoded sets.standalone_sender_fn: async (...) -> dict: out-of-process delivery
for cron jobs that run separately from the gateway. Without this, a
deliver=<name> job fires correctly but the actual send returns
No live adapter for platform '<name>'. Pair with cron_deliver_env_var
for end-to-end cron support. See the docsite for the signature.plugin.yaml requires_env / optional_env rich-dict entries —
auto-populate OPTIONAL_ENV_VARS in hermes_cli/config.py so the setup
wizard surfaces proper descriptions, prompts, password flags, and URLs.Subclassing for platform-specific UX. When a platform has a hard
time-window constraint that the base adapter can't anticipate (LINE's
60s single-use reply token, WhatsApp's 24h session window, etc.), an
adapter can override _keep_typing to layer a mid-flight bubble at a
threshold without expanding the kwarg surface. Always
await super()._keep_typing(...) so the typing heartbeat keeps running,
and tear down your side task in finally. See plugins/platforms/line/
for the full pattern (Template Buttons postback at 45s, RequestCache
state machine, interrupt_session_activity override for /stop
orphans) and the developer-guide page for the prose walkthrough.
Sibling adapters that share behavior. When a single platform has
two transport modes the user picks between — unofficial vs official
APIs, polling vs websocket, library A vs library B — the right
structure is two adapters that share a behavior mixin. WhatsApp does
this: plugins/platforms/whatsapp/adapter.py (Baileys bridge) and
plugins/platforms/whatsapp_cloud/adapter.py (Meta Cloud API) both inherit
from WhatsAppBehaviorMixin in gateway/platforms/whatsapp_common.py.
The mixin owns gating, allow-lists, mention parsing, broadcast
filters, and the WhatsApp-flavored markdown conversion — everything
that's platform-protocol-agnostic. Each adapter owns its transport.
Both register distinct Platform.* enum values so the gateway can run
both simultaneously against different phone numbers. The mixin must
come first in the bases list — class WhatsAppAdapter(Mixin,
BasePlatformAdapter) — so the mixin's format_message overrides
BasePlatformAdapter's generic default.
See plugins/platforms/irc/, plugins/platforms/teams/, and
plugins/platforms/google_chat/ for complete working examples, and
website/docs/developer-guide/adding-platform-adapters.md for the full
plugin guide with code examples and hook documentation.
Plugin-registered native handlers (ctx.register_platform_handler(<platform>, factory)): call
self._wire_plugin_handlers(native_client) once in connect() before your own catch-all handlers. The base
class then handles plugins that load mid-run — the runner calls rewire_plugin_handlers() on every
plugin-loaded event and only factories not yet wired on that native client run. Override it only when your
adapter keeps a second plugin registry (Slack action handlers) or dispatches by registration order with a
catch-all last (Telegram hoists late handlers ahead of core); see gateway/run_plugin_rewire.py.
Checklist for integrating a platform directly into the Hermes core. Use this as a reference when building a built-in adapter — every item here is a real integration point. Missing any of them will cause broken functionality, missing features, or inconsistent behavior.
gateway/platforms/<platform>.py)The adapter is a subclass of BasePlatformAdapter from gateway/platforms/base.py.
| Method | Purpose |
|---|---|
__init__(self, config) |
Parse config, init state. Call super().__init__(config, Platform.YOUR_PLATFORM) |
connect() -> bool |
Connect to the platform, start listeners. Return True on success |
disconnect() |
Stop listeners, close connections, cancel tasks |
send(chat_id, text, ...) -> SendResult |
Send a text message |
send_typing(chat_id) |
Send typing indicator |
send_image(chat_id, image_url, caption) -> SendResult |
Send an image |
get_chat_info(chat_id) -> dict |
Return {name, type, chat_id} for a chat |
| Method | Purpose |
|---|---|
send_document(chat_id, path, caption) |
Send a file attachment |
send_voice(chat_id, path) |
Send a voice message |
send_video(chat_id, path, caption) |
Send a video |
send_animation(chat_id, path, caption) |
Send a GIF/animation |
send_image_file(chat_id, path, caption) |
Send image from local file |
If your platform supports interactive button/menu messages, implement these for a more polished agent experience. They all degrade gracefully to plain text when not overridden:
| Method | Purpose |
|---|---|
send_clarify(chat_id, question, choices, clarify_id, session_key, ...) |
Render the clarify tool's multi-choice question as tappable buttons. Pair with inbound dispatch that routes button taps to tools.clarify_gateway.resolve_gateway_clarify. |
_send_exec_approval_prompt(prompt: ExecApprovalPrompt) |
Render a dangerous-command approval as native buttons. send_exec_approval is a base template method: it builds the shared text (_format_exec_approval, tune via the _EA_* class attrs) and the choice set (prompt.actions = (label, choice, style) rows, choices once/session/always/deny) — you only map those rows to widgets. Inbound dispatch routes to tools.approval.resolve_gateway_approval_card with the card's request id (prompt.request_id), so a press answers the request that card showed. |
send_slash_confirm(chat_id, title, message, session_key, confirm_id, ...) |
Render slash-command confirmations (e.g. /reload-mcp) as Once/Always/Cancel buttons. Inbound dispatch routes to tools.slash_confirm.resolve. |
send_model_picker(...) |
Interactive /model picker. Used by Telegram, Discord, and Slack (Socket Mode). |
send_choice_picker(...) |
Flat single-level picker for finite-choice commands (/reasoning, /fast). Implemented by Telegram (inline keyboard), Discord (select menu), Matrix (reactions), and Feishu (interactive card buttons). Platforms without it fall back to the text status card automatically. |
See plugins/platforms/telegram/adapter.py, plugins/platforms/discord/adapter.py, and plugins/platforms/whatsapp_cloud/adapter.py for reference implementations. The button-callback id convention (cl:<id>:<idx>, appr:<id>:<choice>, sc:<choice>:<id>) is shared across adapters — match it so the gateway-side resolvers work without modification.
def check_<platform>_requirements() -> bool:
"""Check if this platform's dependencies are available."""
self.build_source(...) to construct SessionSource objects (never SessionSource(...)
directly — the transport provenance and profile route are stamped there)self._event_session_key(event) / self._source_session_key(source), never the free
build_session_key() — the seam keys in the owning profile's namespace under a multiplexed
gateway; the advisory lint (scripts/check_profile_scope_patterns.py, pattern P32) flags bothself.handle_message(event) to dispatch inbound messages to the gatewayMessageEvent, MessageType from gateway.platforms.event and SendResult from basecache_image_from_bytes, cache_audio_from_bytes, cache_document_from_bytes for attachmentsMessageDeduplicator (gateway/platforms/helpers.py) held as an adapter
attribute; the runner's reconnect copies its live IDs into the rebuilt adapter, a hand-rolled cache starts emptyMAX_MESSAGE_LENGTH if the platform has message size limitsgateway/config.py)Add the platform to the Platform enum:
class Platform(Enum):
...
YOUR_PLATFORM = "your_platform"
Env credentials reach the config through the plugin's own gateway_env.py (the template is
plugins/platforms/telegram/gateway_env.py), passed to ctx.register_platform as
env_overrides=gateway_env.ENV_OVERRIDES and env_enable_credentials=gateway_env.ENV_ENABLE_CREDENTIALS.
Steps run in order; EnvCred (gateway/platform_env.py) enables the platform when the named env
vars resolve and copies them into extra. Import only gateway.* there: core reads the file
directly, without the adapter, when the plugin is not loaded.
ENV_ENABLE_CREDENTIALS = ("YOUR_PLATFORM_TOKEN",)
ENV_OVERRIDES = (
EnvCred(Platform.YOUR_PLATFORM, ("YOUR_PLATFORM_TOKEN",), token="YOUR_PLATFORM_TOKEN"),
home_step(Platform.YOUR_PLATFORM, "YOUR_PLATFORM_HOME_CHANNEL"),
)
Every read goes through gateway/config.py::_getenv (the active profile's secret scope when one
is bound, os.environ otherwise). Never os.getenv here and never write os.environ: under
gateway.multiplex_profiles the process env is the DEFAULT profile's, so a raw read enables your
platform for the wrong profile with the wrong credentials, and a write pins one profile's policy
process-wide (first profile wins). Adapter-side reads use gateway.platforms._shared.get_scoped_secret
/ extra_or_secret.
If your platform is "configured" without a token/api_key (WhatsApp uses the enabled flag,
Signal the extra dict), declare config_connected_fn on the entry; get_connected_platforms()
reads it.
gateway/run.py)Add to _instantiate_adapter():
elif platform == Platform.YOUR_PLATFORM:
from gateway.platforms.your_platform import YourAdapter, check_your_requirements
if not check_your_requirements():
logger.warning("Your Platform: dependencies not met")
return None
return YourAdapter(config)
_create_adapter() wraps this factory and binds every successful adapter to
its GatewayRunner. Do not construct platform adapters in lifecycle call sites;
startup and reconnect must keep using the wrapper so profile routing is wired
before connect().
gateway/pairing.py, gateway/authz_mixin.py)Declare the allowlist names in the plugin's gateway_env.py and pass them with
**gateway_env.AUTHZ; pairing, the authz ladder, the dashboard and the startup policy gate read
them from the entry, and from this file when the entry is missing (safe mode, plugin disabled) or a
user plugin overriding yours omits them:
AUTHZ = {
"allowed_users_env": "YOUR_PLATFORM_ALLOWED_USERS",
"allow_all_env": "YOUR_PLATFORM_ALLOW_ALL_USERS",
# optional: "allow_bots_env": "YOUR_PLATFORM_ALLOW_BOTS",
# optional, adapters that gate DMs/groups themselves: "own_policy_env": ("..._DM_POLICY", "..._GROUP_POLICY"),
}
_is_user_authorized() reads every gate through _shared.platform_gate_env (_auth_env), which
answers from the routed profile's secret scope under multiplex — never add an os.getenv here.
gateway/session.py)If your platform needs extra identity fields (e.g., Signal's UUID alongside
phone number), add them to the SessionSource dataclass with Optional defaults,
and update to_dict(), from_dict(), and build_source() in base.py.
platform_hint)Declare platform_hint= on ctx.register_platform (keep the text in a light sibling such as
adapter_hint.py) so the agent knows what platform it's on. agent/prompt_builder.py::PLATFORM_HINTS
holds only core surfaces (CLI, TUI, API server, ...):
PLATFORM_HINT = (
"You are on Your Platform. "
"Describe formatting capabilities, media support, etc."
)
Without this, the agent won't know it's on your platform and may use inappropriate formatting (e.g., markdown on platforms that don't render it).
toolsets.py)Add a named toolset for your platform:
"hermes-your-platform": {
"description": "Your Platform bot toolset",
"tools": _HERMES_CORE_TOOLS,
"includes": []
},
And add it to the hermes-gateway composite:
"hermes-gateway": {
"includes": [..., "hermes-your-platform"]
}
cron/scheduler.py)Add to platform_map in _deliver_result():
platform_map = {
...
"your_platform": Platform.YOUR_PLATFORM,
}
Without this, cronjob(action="create", deliver="your_platform", ...) silently fails.
tools/send_message_tool.py)Add to platform_map in send_message_tool():
platform_map = {
...
"your_platform": Platform.YOUR_PLATFORM,
}
Add routing in _send_to_platform():
elif platform == Platform.YOUR_PLATFORM:
return await _send_your_platform(pconfig, chat_id, message)
Implement _send_your_platform() — a standalone async function that sends
a single message without requiring the full adapter (for use by cron jobs
and the send_message tool outside the gateway process).
Update the tool schema target description to include your platform example.
tools/cronjob_tools.py)Update the deliver parameter description and docstring to mention your
platform as a delivery option.
gateway/channel_directory.py)If your platform can't enumerate chats (most can't), add it to the session-based discovery list:
for plat_name in ("telegram", "whatsapp", "signal", "your_platform"):
hermes_cli/status.py)Add to the platforms dict in the Messaging Platforms section:
platforms = {
...
"Your Platform": ("YOUR_PLATFORM_TOKEN", "YOUR_PLATFORM_HOME_CHANNEL"),
}
hermes_cli/gateway.py)Add to the _PLATFORMS list:
{
"key": "your_platform",
"label": "Your Platform",
"emoji": "📱",
"token_var": "YOUR_PLATFORM_TOKEN",
"setup_instructions": [...],
"vars": [...],
}
If your platform needs custom setup logic (connectivity testing, QR codes,
policy choices), add a _setup_your_platform() function and route to it
in the platform selection switch.
Update _platform_status() if your platform's "configured" check differs
from the standard bool(get_env_value(token_var)).
agent/redact.py)If your platform uses sensitive identifiers (phone numbers, etc.), add a
regex pattern and redaction function to agent/redact.py. This ensures
identifiers are masked in ALL log output, not just your adapter's logs.
| File | What to update |
|---|---|
README.md |
Platform list in feature table + documentation table |
AGENTS.md |
Gateway description + env var config section |
website/docs/user-guide/messaging/<platform>.md |
NEW — Full setup guide (see existing platform docs for template) |
website/docs/user-guide/messaging/index.md |
Architecture diagram, toolset table, security examples, Next Steps links |
website/docs/reference/environment-variables.md |
All env vars for the platform |
tests/gateway/test_<platform>.py)Recommended test coverage:
_apply_env_overridesOptional but valuable:
After implementing everything, verify with:
# All tests pass
python -m pytest tests/ -q
# Grep for your platform name to find any missed integration points
grep -r "telegram\|discord\|whatsapp\|slack" gateway/ tools/ agent/ cron/ hermes_cli/ toolsets.py \
--include="*.py" -l | sort -u
# Check each file in the output — if it mentions other platforms but not yours, you missed it