Chapter 8: Gateway Operations

Gateway is the cuttlefish's heart — it runs continuously, connects all chat platforms, and schedules tasks. This chapter teaches you how to keep the heart beating steadily and how to perform first aid when something goes wrong.

Gateway Architecture Recap

Feishu ──┐                    ┌──→ AI Agent processing
Telegram ──┤                │
Discord ──┼──→ Gateway ─────┤──→ Cron scheduler (every 60s)
Slack ──┤     (single process) │
... ──┘                    └──→ Session management

Gateway uses a single-process architecture — one background process handles connections, message routing, session management, and scheduled task scheduling for all platforms.

---

Installation & Startup

First-Time Installation

# Interactive configuration wizard
hermes gateway

# Install as a service (auto-start on boot)
hermes gateway install        # macOS: launchd user service
hermes gateway install --system  # Linux: systemd system service

Avoid Conflicts

Do not install both user and system services simultaneously. Hermes will detect this and warn you, because start/stop/status behavior becomes ambiguous.

Daily Management Commands

# Start
hermes gateway start

# Stop
hermes gateway stop

# Restart
hermes gateway restart

# View status
hermes gateway status

# View logs
hermes gateway logs

---

macOS Service Management

macOS uses launchd. The generated plist file is located at:

~/Library/LaunchAgents/ai.hermes.gateway.plist

The plist contains three environment variables:

• PATH — Ensures the hermes command is discoverable
• HOME — User home directory
• HERMES_HOME — Hermes data directory (default ~/.hermes)

Uninstall the Service

hermes gateway uninstall

Linux Service Management

Linux uses systemd:

# Install as system service (auto-start on boot, ideal for VPS)
hermes gateway install --system

# User service (ideal for dev machines)
hermes gateway install

Service naming rules:

• Default installation (~/.hermes): hermes-gateway
• Multi-instance installation: hermes-gateway-<hash>

The hermes gateway command automatically locates the correct service.

---

Multi-Instance Deployment

If you run multiple Hermes instances on the same machine (with different HERMES_HOME):

# Instance 1 (default)
export HERMES_HOME=~/.hermes
hermes gateway start

# Instance 2
export HERMES_HOME=~/.hermes-work
hermes gateway start

Each instance has independent:

• Configuration files (.env, config.yaml)
• Skill directories (skills/)
• Cron tasks (cron/)
• Session storage (state.db)
• systemd service name

---

Session Management

Session Persistence

Gateway maintains independent sessions for each chat. Sessions persist across messages — the Agent remembers your conversation context.

Reset Policy

Sessions automatically reset based on a configurable policy:

# ~/.hermes/gateway.json
{
  "session_reset_policy": {
    "telegram": "on_restart",
    "feishu": "on_idle_30m"
  }
}

Manual Reset

In a chat, send:

/reset

Background Sessions

/background Analyze this project's code structure for me

Runs in a separate background session without blocking the main chat. Results are automatically sent back when complete.

---

Security Mechanisms

User Allowlist

By default, Gateway rejects all unauthorized users.

Method 1: Allow all users (development/testing only)

# ~/.hermes/.env
GATEWAY_ALLOW_ALL_USERS=true

Method 2: Specify user IDs (recommended for production)

GATEWAY_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy

Method 3: DM pairing code (recommended)

No need to manually configure user IDs. When an unauthorized user DMs the bot for the first time, they receive a one-time pairing code:

User: Hello
Bot: 🔒 You are not on the allowlist.
     Please run the following command in the Hermes CLI to complete pairing:
     hermes gateway pair <code>
     Pairing code is valid for 1 hour.

# In the Hermes CLI
hermes gateway pair <code>

Pairing code features:

• 1-hour validity period
• Rate-limited
• Generated using cryptographic randomness

Production Must-Read

Never use GATEWAY_ALLOW_ALL_USERS=true in production. Your Agent has terminal access — anyone who can reach the bot can execute commands on your machine.

---

Monitoring & Troubleshooting

View Logs

# Live logs
hermes gateway logs

# systemd environment
journalctl -u hermes-gateway -f

# launchd environment
tail -f ~/Library/LaunchAgents/ai.hermes.gateway.plist

Health Check

hermes gateway status

Common Issues

Problem	Possible Cause	Troubleshooting
Gateway fails to start	Port in use / config error	hermes doctor
Feishu disconnection	WebSocket timeout	Check network, view logs
Cron not executing	Gateway not running	hermes gateway status
Bot not responding	User not on allowlist	Check GATEWAY_ALLOWED_USERS
Dual instance conflict	Both user + system service installed	Uninstall one: hermes gateway uninstall
No auto-start after macOS reboot	launchd service not installed	hermes gateway install

---

Home Chat

Home Chat is a special chat window used for receiving:

• Cron task results
• Cross-platform notifications
• System reminders

How to set it:

# Send in the target chat
/set-home

Or pre-configure:

# ~/.hermes/.env
FEISHU_HOME_CHAT_ID=oc_xxxxxxxxxxxxx
TELEGRAM_HOME_CHAT_ID=-100xxxxxxxxxx

---

Progress Notifications

Control how progress is displayed when the Agent is working:

# ~/.hermes/config.yaml
display:
  tool_progress: true           # Show tool execution progress
  background_process_notifications: true  # Background task notifications

Also configurable via environment variable:

HERMES_DISPLAY_BACKGROUND_PROCESS_NOTIFICATIONS=true

Further Reading

• Official docs: Messaging Gateway
• Gateway internals: Gateway Internals

---