Hermes LINE Bridge

Connect Hermes Agent to LINE Messaging API.

Hermes Agent supports 20+ messaging platforms — but not LINE. This bridge fills that gap.

Features

• Text messages — Full conversation with Hermes Agent
• Image analysis — Vision-capable models analyze images sent in LINE (auto-saved to disk)
• File notifications — File uploads are acknowledged and logged
• Persistent memory — Hermes remembers conversations across sessions
• Per-user history — Separate conversation context for each LINE user
• Group chat support — Works in LINE groups (messages tagged with group ID)
• Docker Compose — One command to run both Hermes Agent and the bridge

Architecture

LINE (user sends message)
  → LINE Platform (webhook)
  → Hermes LINE Bridge (FastAPI)
      ├── Text → forward to Hermes API
      ├── Image → download via LINE Content API
      │          → save to disk + JSONL log
      │          → Base64 encode → Hermes API (vision)
      └── File → notify Hermes with filename
  → Hermes Agent (OpenAI-compatible API Server)
      ├── SOUL.md (persona definition)
      ├── memories/ (persistent across sessions)
      └── LLM (Anthropic, OpenRouter, Ollama, etc.)
  → LINE reply

Quick Start

1. Clone

git clone https://github.com/gdalabs/hermes-line-bridge.git
cd hermes-line-bridge

2. Configure

# LINE credentials
cp .env.example .env
# Edit .env: LINE_CHANNEL_SECRET, LINE_CHANNEL_ACCESS_TOKEN, HERMES_API_KEY

# Hermes Agent
cp hermes/config.example.yaml hermes/config.yaml
cp hermes/SOUL.example.md hermes/SOUL.md

# Hermes secrets
cat > hermes/.env << 'EOF'
ANTHROPIC_API_KEY=your-api-key
API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8100
API_SERVER_KEY=your-hermes-api-key
GATEWAY_ALLOW_ALL_USERS=true
EOF

3. Launch

docker compose up -d

4. Expose webhook

Use a tunnel to expose the bridge to the internet:

# Cloudflare Tunnel (recommended)
cloudflared tunnel --url http://localhost:3000

# Or ngrok
ngrok http 3000

5. Set LINE webhook

In LINE Developers Console:

• Messaging API → Webhook URL → https://your-domain.com/webhook
• Enable "Use webhook"

Done! Send a message to your LINE Bot.

Configuration

All configuration is via environment variables:

Variable	Description	Default
LINE_CHANNEL_SECRET	LINE Messaging API channel secret	(required)
LINE_CHANNEL_ACCESS_TOKEN	LINE Messaging API access token	(required)
HERMES_API_URL	Hermes Agent API Server URL	http://hermes:8100
HERMES_API_KEY	Bearer token for Hermes API	(required)
HERMES_MODEL	Model name to send to Hermes	hermes-agent
IMAGE_SAVE_DIR	Directory to save received images	/data/images
MAX_HISTORY	Max messages per user in memory	40

Customization

Persona (SOUL.md)

Edit hermes/SOUL.md to define your bot's personality and behavior. See hermes/SOUL.example.md for a starting point.

LLM Provider

Edit hermes/config.yaml to switch LLM providers:

model:
  provider: "openrouter"    # 200+ models
  default: "anthropic/claude-haiku-4-5-20251001"

Supported: Anthropic, OpenRouter, OpenAI, Ollama, NVIDIA NIM, Hugging Face, and more.

Enable Browser Tools

For web search capabilities:

tools:
  browser: true

Running Multiple Bots

Each bot needs its own Hermes instance with separate memory:

Bot A (port 3000/8100) → hermes-a/ (context A)
Bot B (port 3001/8200) → hermes-b/ (context B)

Conversations never mix between instances.

Image Handling

When a user sends an image in LINE:

1. The bridge downloads it via LINE Content API
2. Saves to IMAGE_SAVE_DIR as YYYYMMDD_HHMMSS_user_msgid.jpg
3. Logs metadata to image_log.jsonl
4. Sends the image (Base64) to Hermes for vision analysis
5. Hermes responds with its analysis

Requires a vision-capable model (e.g., Claude Haiku 4.5, GPT-4o).

LINE-Friendly Output Tips

LINE's mobile display is narrow. For best results, configure your SOUL.md with:

• No markdown tables (they break on LINE's narrow mobile display)
• Use short paragraphs with generous line breaks
• Keep messages under 300 characters when possible
• Bullet points with - for readability

Health Check

curl http://localhost:3000/health
# {"status":"ok","service":"hermes-line-bridge"}

Cost

Using Claude Haiku 4.5:

Usage	Messages/day	Monthly cost
Light	10-20	~$3-5
Normal	50-100	~$10-20
With images	50 + 20 images	~$15-25

Requirements

• Docker + Docker Compose
• LINE Developers account (create one)
• LLM API key (Anthropic, OpenRouter, etc.)

License

MIT

Author

GDA Labs