Hermes Telegram Miniapp
Apps & Automationhermes-telegram-miniappHermes Telegram Miniapp is an Agent Skill for apps & automation published in the clawvader-tech/hermes-telegram-miniapp repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Install and operate the Hermes Telegram Mini App — FastAPI + React SPA dashboard served on port 9119, exposed via Cloudflare tunnel, with Ed25519 Telegram auth. Covers setup, auth, tunnel, bot menu, and troubleshooting.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/clawvader-tech/hermes-telegram-miniapp/blob/HEAD/.hermes/skills/hermes-telegram-miniapp/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/hermes-telegram-miniapp, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Hermes Telegram Mini App — Setup & Operations Skill
What It Is
A Telegram Mini App giving Hermes users a full-featured mobile dashboard: streaming AI chat, system status, cron job management, agent spawning, session browsing, analytics, logs, skills management, config editing, and API key management — 10 pages, mobile-first, dark TUI aesthetic.
Repo: https://github.com/clawvader-tech/hermes-telegram-miniapp
Architecture
Phone (Telegram App)
→ Mini App (React SPA in Telegram WebView)
→ HTTPS Reverse Proxy (Cloudflare Tunnel — YOUR domain)
→ FastAPI Web Server (localhost:9119)
→ Hermes Agent (tmux sessions, CLI tools)
→ Local Vision (LFM2-VL-450M, port 8080)
→ Local OCR (GLM-OCR, port 8081)
Prerequisites
- Hermes Agent installed at
~/.hermes/hermes-agent/ - Python venv:
~/.hermes/hermes-agent/venv/ - Telegram bot token (from @BotFather)
- Numeric Telegram user ID (from @userinfobot — it's a NUMBER, not a username)
cryptographyPython package:pip install cryptographycloudflaredinstalled for tunneling
Step-by-Step Setup
1. Env Vars
Add to ~/.hermes/.env:
TELEGRAM_BOT_TOKEN=your_bot_token_from_botfather
TELEGRAM_OWNER_ID=your_numeric_user_id
API_SERVER_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))")
2. Build the Frontend
cd ~/.hermes/hermes-agent && source venv/bin/activate
cd web && npm install && npm run build && cd ..
Output goes to hermes_cli/web_dist/.
3. Start the Web Server
cd ~/.hermes/hermes-agent && source venv/bin/activate
nohup python -B -c "from hermes_cli.web_server import start_server; start_server('127.0.0.1', 9119, False)" > /tmp/hermes-dashboard.log 2>&1 &
4. Expose via Cloudflare Tunnel
Option A — Quick tunnel (URL changes on restart):
cloudflared tunnel --url http://localhost:9119
Fine for testing. Note the URL.
Option B — Named tunnel (stable URL, recommended):
cloudflared tunnel create hermes
cloudflared tunnel route dns hermes your-domain.example.com
cloudflared tunnel run hermes
Replace your-domain.example.com with your actual domain.
5. Set the Bot Menu Button
curl -s "https://api.telegram.org/bot${TELEGRAM_BOT_TOKEN}/setChatMenuButton" \
-H "Content-Type: application/json" \
-d '{"chat_id": YOUR_USER_ID, "menu_button": {"type": "web_app", "text": "Dashboard", "web_app": {"url": "https://YOUR_DOMAIN/"}}}'
Get your numeric user ID from @userinfobot. The URL must be HTTPS.
6. Verify
# Local health check
curl -s http://localhost:9119/api/status
# Tunnel health check
curl -s https://YOUR_DOMAIN/api/status
Open the mini app by tapping the menu button in your Telegram bot chat.
Pages (10)
| Page | Description |
|---|---|
| Chat | Streaming AI chat with file attachments (images, PDFs, CSVs), agent spawn |
| Status | CPU/mem/disk gauges, process list, recent sessions |
| Agents | Spawn/kill/message independent Hermes instances in tmux (max 5) |
| Sessions | Browse/search past conversations |
| Analytics | Token usage charts, model stats, cost tracking |
| Logs | Live log viewer with filtering |
| Cron | Create/edit/pause/delete/run scheduled tasks |
| Skills | Browse and toggle agent skills |
| Config | Form mode + raw YAML editor |
| Keys | API key management by provider |
Auth Architecture
Request arrives
→ true localhost (no X-Forwarded-For)? → skip auth
→ static asset path? → serve without auth
→ valid Ed25519 Telegram initData? → allow
→ Authorization: Bearer <API_SERVER_KEY>? → allow
→ else → 401
Ed25519 public key (verify at https://core.telegram.org/bots/webapps):
e7bf03a2fa4602af4580703d88dda5bb59f32ed8b02a56c187fe7d34caed242d
64 hex chars (32 bytes). Requires the cryptography Python package.
Server Commands
# Start
cd ~/.hermes/hermes-agent && source venv/bin/activate
nohup python -B -c "from hermes_cli.web_server import start_server; start_server('127.0.0.1', 9119, False)" > /tmp/hermes-dashboard.log 2>&1 &
# Restart script (save to /tmp/restart-dashboard.sh)
#!/bin/bash
kill $(pgrep -f "web_server.*start_server" | head -1) 2>/dev/null
sleep 1
cd ~/.hermes/hermes-agent && source venv/bin/activate
nohup python -B -c "from hermes_cli.web_server import start_server; start_server('127.0.0.1', 9119, False)" >> /tmp/hermes-dashboard.log 2>&1 &
# Health check
curl -s http://localhost:9119/api/status | python3 -m json.tool
Troubleshooting
| Problem | Fix |
|---|---|
cryptography not found | pip install cryptography |
| 401 Unauthorized | Check TELEGRAM_OWNER_ID is numeric, not username |
| 404 on routes | Restart the web server after frontend rebuild |
| Bot button not appearing | Include chat_id in setChatMenuButton request |
| initData keeps expiring | Close and reopen the mini app (24hr window) |
| Tunnel URL changes | Set up a named Cloudflare tunnel with your domain |
| Port already in use | kill $(pgrep -f "web_server.*start_server") first |
Key Files
| File | Purpose |
|---|---|
hermes_cli/web_server.py | FastAPI backend — all endpoints + TG auth middleware |
hermes_cli/web_dist/ | Built frontend (~339KB JS + 48KB CSS) |
web/src/App.tsx | React app shell — 10-tab navigation |
web/src/pages/*.tsx | Individual page components |
web/src/lib/api.ts | Frontend API client with auth helpers |
Install This Skill (for Hermes Agents)
Give your agent this repo URL and ask it to install:
https://github.com/clawvader-tech/hermes-telegram-miniapp/tree/main/.hermes/skills/hermes-telegram-miniapp/SKILL.md
Or place the SKILL.md at ~/.hermes/skills/hermes-telegram-miniapp/SKILL.md on the target machine.