hermes/README.md

Hermes — OpenClaw Web Interface

Prod: https://chat.jqxp.org · wss://chat.jqxp.org/ws Dev: https://dev.jqxp.org

---

Stack

hermes/
  backend/    Bun + TypeScript    :3001 prod / :3003 dev
  frontend/   Vue 3 + Vite        :8443 dev  / jqxp.org prod (static)

Architecture

Browser(s)
    │  WebSocket /ws + HTTP /api/*
    ▼
server.ts  (Bun.serve)
    ├── auth.ts            token → user, session tokens
    ├── gateway.ts         upstream WS → openclaw gateway :18789
    ├── session-sm.ts      per-connection state machine
    ├── session-watcher.ts JSONL tail → WS events
    ├── hud-builder.ts     HUD event factory, result builders, path helpers
    ├── message-filter.ts  strip sensitive values from tool output
    └── mcp/               MCP Streamable HTTP server
        ├── index.ts       auth, routing, key management
        ├── dev.ts         health, subscribe, push_state tools
        ├── events.ts      in-memory event queue + long-poll
        ├── system.ts      start/stop/restart/deploy tools
        └── fs.ts          remote file read/write/edit/grep

See backend/README.md and frontend/README.md for details.

Dev

On openclaw VM (tmux sessions)

# Backend (auto-restarts on file change)
cd hermes/backend
PORT=3003 ~/.bun/bin/bun --watch run server.ts    # tmux: hermes-bun

# Frontend (Vite HMR)
cd hermes/frontend
bun run dev                                        # tmux: webchat-vite → :8443

From Titan host (Claude Code workspace)

Local mirror: D:/ClaudeCode/Titan/Openclaw/ ↔ ~/.openclaw/ on openclaw VM.

# Pull entire project
rsync -avz --exclude='node_modules' --exclude='dist' --exclude='.git' \
  openclaw:~/.openclaw/workspace-titan/projects/hermes/ \
  /d/ClaudeCode/Titan/Openclaw/workspace-titan/projects/hermes/

# Edit locally with Claude Code (Read/Edit tools — no shell escaping issues)

# Push backend (bun --watch auto-restarts)
rsync -avz --exclude='node_modules' --exclude='dist' --exclude='.git' \
  /d/ClaudeCode/Titan/Openclaw/workspace-titan/projects/hermes/backend/ \
  openclaw:~/.openclaw/workspace-titan/projects/hermes/backend/

# Push frontend (Vite HMR picks up instantly)
rsync -avz --exclude='node_modules' --exclude='dist' --exclude='.git' \
  /d/ClaudeCode/Titan/Openclaw/workspace-titan/projects/hermes/frontend/ \
  openclaw:~/.openclaw/workspace-titan/projects/hermes/frontend/

Deploy

# Frontend → static hosting
cd hermes/frontend && npm run build
rsync -avz --delete dist/ u116526981@access1007204406.webspace-data.io:~/jqxp/

# Backend prod restart
sudo systemctl restart openclaw-web-gateway.service
curl https://chat.jqxp.org/health

Ports

:3001   prod backend    systemd: openclaw-web-gateway.service
:3003   dev backend     tmux: hermes-bun
:8443   dev frontend    tmux: webchat-vite

Network

Browser → Cloudflare Tunnel → RouterVM → OpenClaw VM :3001 → gateway :18789

Features (0.6.42)

• Multi-modal chat: text, images, PDFs, audio recording
• Audio STT via ElevenLabs Scribe v2 (mic → transcript → agent)
• TTS via ElevenLabs (speaker icon on assistant messages, player bar)
• Permanent sidebar rail with overlay expand, responsive
• Previous session history (server-fetched, load more)
• MCP server with 36+ tools (fs, system, deck, dev, takeover)
• Real-time MCP event loop (dev_subscribe + dev_push_state)
• Interactive dev tools: counter game, action picker, confetti
• Automated test runner via Nextcloud Deck + takeover bridge
• WebGL particle background (theme-aware)
• Deploy to prod via MCP (system_deploy_prod)

Open

• Token management (tokens hardcoded in auth.ts)
• Room mode (shared session, multiple users)
• User message lifecycle (msgId-based updates, dedup)
• Rename project/domain