Hermes Kanban Mini App

A community-ready Telegram Mini App and browser dashboard for viewing and operating Hermes Agent Kanban boards from mobile or desktop.

Status: local MVP. The repository is prepared for a future public GitHub push, but no remote is created by this task.

What it does

• Shows Hermes Kanban columns: triage, todo, ready, running, blocked, done, archived.
• Opens task details with body, events, runs and log tail.
• Creates tasks with assignee, priority, workspace kind, goal mode and runtime options.
• Adds comments and runs common actions: assign, promote, block, unblock, archive, dispatch.
• Supports Telegram Mini App theme variables and server-side Telegram initData validation.

Architecture

Telegram Mini App / Browser
        |
        | HTTPS in production, Vite proxy in dev
        v
React + TypeScript frontend
        |
        | /api/* with optional X-Telegram-Init-Data
        v
FastAPI backend
        |
        | fixed subprocess argv, shell=False
        v
hermes kanban CLI
        |
        v
Hermes Kanban board

Screenshot placeholder: run the frontend locally and replace this section with screenshots before publishing the GitHub repository.

Prerequisites

• Hermes Agent installed with Kanban enabled.
• Python 3.11+.
• Node.js 20+ (tested with Node 24).
• Telegram bot from BotFather for Mini App production mode.
• HTTPS public URL for Telegram Mini App production usage.

Local development

git clone <your-future-repo-url> hermes-kanban-miniapp
cd hermes-kanban-miniapp
cp .env.example .env

Backend:

python3 -m venv .venv
. .venv/bin/activate
pip install -e backend[dev]
uvicorn app.main:app --app-dir backend --reload --host 127.0.0.1 --port 8000

Frontend:

cd frontend
npm install
npm run dev

Open http://localhost:5173. In KANBAN_UI_AUTH_MODE=dev or none, the browser works without Telegram.

Environment variables

See .env.example.

Important settings:

• HERMES_BIN: Hermes executable, default hermes.
• HERMES_HOME: Hermes home directory for the target profile.
• HERMES_KANBAN_BOARD: default board slug.
• KANBAN_UI_AUTH_MODE: telegram, dev or none.
• TELEGRAM_BOT_TOKEN: bot token used only by backend for initData validation.
• TELEGRAM_ALLOWED_USER_IDS: optional comma-separated Telegram user id allowlist.
• KANBAN_UI_ALLOWED_ORIGINS: CORS allowlist.
• KANBAN_UI_FRONTEND_DIST_DIR: optional built frontend directory for single-container serving.
• VITE_API_BASE_URL: frontend API base URL for production builds.

Telegram Mini App setup

1. Open BotFather in Telegram.
2. Create or choose a bot.
3. Use /setdomain and set the HTTPS domain that serves this app.
4. Use /setmenubutton or create a Web App button and point it at your HTTPS frontend URL.
5. On the backend, set:
   • KANBAN_UI_AUTH_MODE=telegram
   • TELEGRAM_BOT_TOKEN=<your bot token>
   • optionally TELEGRAM_ALLOWED_USER_IDS=123,456
6. Never put the bot token into frontend env vars or committed files.

Production deployment notes

Telegram Mini Apps require HTTPS. Put the frontend and backend behind a reverse proxy such as Caddy, Nginx, Traefik or Cloudflare Tunnel. Configure CORS so the backend only accepts your frontend origin.

Systemd example:

[Unit]
Description=Hermes Kanban Mini App API
After=network.target

[Service]
WorkingDirectory=/opt/hermes-kanban-miniapp
EnvironmentFile=/opt/hermes-kanban-miniapp/.env
ExecStart=/opt/hermes-kanban-miniapp/.venv/bin/uvicorn app.main:app --app-dir backend --host 127.0.0.1 --port 8000
Restart=on-failure

[Install]
WantedBy=multi-user.target

Build frontend for static hosting:

cd frontend
npm ci
npm run build

The included Dockerfile builds the frontend and serves it from the FastAPI container on port 8000. For same-origin Docker deployment, leave VITE_API_BASE_URL empty at build time and expose only the backend container.

Security model

• Backend accepts only fixed API actions mapped to fixed Hermes Kanban CLI subcommands.
• Subprocess calls use argv lists and shell=False.
• Telegram initData is validated according to Telegram WebApp signing rules in telegram auth mode.
• Optional Telegram user allowlist rejects unknown users.
• CORS is restrictive and configured by env.
• .env is ignored by git; .env.example contains placeholders only.

Known limitations

• The adapter prefers Hermes CLI JSON output. If a local Hermes version lacks JSON for a command, parsing is conservative and may return raw text for some endpoints.
• No drag-and-drop yet; actions are button-based.
• No SSE yet; running boards auto-refresh every 2.5 seconds, otherwise every 5 seconds.
• No GitHub remote is created until the owner/name are confirmed and auth is configured.

Tests

Backend:

. .venv/bin/activate
pytest backend/tests -q

Frontend:

cd frontend
npm test
npm run build