83 lines
3.0 KiB
Markdown
83 lines
3.0 KiB
Markdown
---
|
|
title: Hermes Deployment Patterns
|
|
created: '2026-05-29'
|
|
updated: '2026-05-29'
|
|
type: concept
|
|
namespace: personal
|
|
tags: [hermes, architecture, agent, eagle, kraken, infra]
|
|
sources: []
|
|
confidence: medium
|
|
related:
|
|
- "[[tech/hermes-eagle-mac]]"
|
|
- "[[tech/hermes-docker-kraken]]"
|
|
- "[[tech/hermes-kraken-api]]"
|
|
- "[[personal-os-architecture]]"
|
|
---
|
|
|
|
# Hermes Deployment Patterns
|
|
|
|
Three distinct ways Hermes runs in the Personal OS ecosystem. Each serves
|
|
a different access model and client type.
|
|
|
|
## Pattern 1: Eagle Native (Mac M4)
|
|
|
|
**Where:** Eagle Mac M4 Max, native process (not Docker)
|
|
**Transport:** Zulip (Docker)
|
|
**Model backend:** `openclaw-claude-proxy` on port 3456 — wraps
|
|
`claude --print` as an OpenAI-compatible endpoint, preserving tool_use.
|
|
**Autostart:** launchd (`ai.claude-proxy.plist`)
|
|
|
|
**Why native:** Mac file system access, MCP tools (obsidian-mcp), and the
|
|
cron wiki-curation job all need full host access. Docker would require
|
|
volume mounts for every integration.
|
|
|
|
**Key pitfall:** `claude-proxy` wrapper script must `source ~/.hermes/.env`
|
|
explicitly — launchd does not inherit login session env. See
|
|
[[tech/hermes-eagle-mac]].
|
|
|
|
## Pattern 2: Kraken Docker (RPi5)
|
|
|
|
**Where:** Kraken RPi5, `docker run` (not compose)
|
|
**Transport:** Zulip (same instance or separate)
|
|
**Model backend:** Gemini or OpenRouter via Hermes gateway
|
|
**Autostart:** `--restart unless-stopped` on the container
|
|
|
|
**Why docker run, not compose:** explicit restart behavior; avoids accidental
|
|
`docker compose down` wipes. Config volume: `~/.hermes` on Kraken host.
|
|
|
|
See [[tech/hermes-docker-kraken]].
|
|
|
|
## Pattern 3: Kraken API Server (OpenAI-compat)
|
|
|
|
**Where:** Kraken RPi5, same hermes-kraken container
|
|
**Transport:** HTTPS via Cloudflare Tunnel (`kraken.qentra.top`)
|
|
**Model backend:** Gemini / OpenRouter (same gateway)
|
|
**Clients:** Android Aide app (BYOK → Custom Endpoint), any OpenAI SDK
|
|
|
|
**Why Cloudflare Tunnel:** no port-forwarding on home router required.
|
|
The tunnel terminates at cloudflared running with `network_mode: host`,
|
|
hitting `localhost:8642` directly.
|
|
|
|
See [[tech/hermes-kraken-api]].
|
|
|
|
## Comparison
|
|
|
|
| Dimension | Eagle Native | Kraken Docker | Kraken API |
|
|
|-----------|-------------|---------------|-----------|
|
|
| Model | claude-sonnet via proxy | Gemini/ORouter | Gemini/ORouter |
|
|
| Transport | Zulip | Zulip | HTTPS REST |
|
|
| Clients | Cron, MCP tools | Zulip bot clients | Mobile / OpenAI SDK |
|
|
| External access | No | No | Yes (CF Tunnel) |
|
|
| MCP/tools | Full (host access) | Docker volumes | Not applicable |
|
|
| Rate limits | Claude OAuth (proxy workaround) | API keys | API keys |
|
|
|
|
## Design Principle
|
|
|
|
Hermes deployments follow the client's access model:
|
|
- **Interactive/tool-heavy** → Eagle native (full host, MCP)
|
|
- **Always-on background** → Kraken Docker (low-power, 24/7)
|
|
- **Mobile / external** → Kraken API server (HTTPS, standard protocol)
|
|
|
|
This avoids running a single large instance with conflicting requirements.
|
|
See [[personal-os-architecture]] for the full system overview.
|