Files

teknium1 d87a1615ce docs: add ACP and internal systems implementation guides

- add ACP user and developer docs covering setup, lifecycle, callbacks,
  permissions, tool rendering, and runtime behavior
- add developer guides for agent loop, provider runtime resolution,
  prompt assembly, context caching/compression, gateway internals,
  session storage, tools runtime, trajectories, and cron internals
- refresh architecture, quickstart, installation, CLI reference, and
  environments docs to link the new implementation pages and ACP support

2026-03-14 00:29:48 -07:00

2.4 KiB

Raw Blame History

sidebar_position, title, description

sidebar_position	title	description
7	Gateway Internals	How the messaging gateway boots, authorizes users, routes sessions, and delivers messages

Gateway Internals

The messaging gateway is the long-running process that connects Hermes to external platforms.

Key files:

gateway/run.py
gateway/config.py
gateway/session.py
gateway/delivery.py
gateway/pairing.py
gateway/channel_directory.py
gateway/hooks.py
gateway/mirror.py
gateway/platforms/*

Core responsibilities

The gateway process is responsible for:

loading configuration from .env, config.yaml, and gateway.json
starting platform adapters
authorizing users
routing incoming events to sessions
maintaining per-chat session continuity
dispatching messages to AIAgent
running cron ticks and background maintenance tasks
mirroring/proactively delivering output to configured channels

Config sources

The gateway has a multi-source config model:

environment variables
~/.hermes/gateway.json
selected bridged values from ~/.hermes/config.yaml

Session routing

gateway/session.py and GatewayRunner cooperate to map incoming messages to active session IDs.

Session keying can depend on:

platform
user/chat identity
thread/topic identity
special platform-specific routing behavior

Authorization layers

The gateway can authorize through:

platform allowlists
gateway-wide allowlists
DM pairing flows
explicit allow-all settings

Pairing support is implemented in gateway/pairing.py.

Delivery path

Outgoing deliveries are handled by gateway/delivery.py, which knows how to:

deliver to a home channel
resolve explicit targets
mirror some remote deliveries back into local history/session tracking

Hooks

Gateway events emit hook callbacks through gateway/hooks.py. Hooks are local trusted Python code and can observe or extend gateway lifecycle events.

Background maintenance

The gateway also runs maintenance tasks such as:

cron ticking
cache refreshes
session expiry checks
proactive memory flush before reset/expiry

Honcho interaction

When Honcho is enabled, the gateway can keep persistent Honcho managers aligned with session lifetimes and platform-specific session keys.

2.4 KiB Raw Blame History