robbyczgw-cla/hermes-ui-plus

HUI+ (Hermes UI+)

Don't just read your agent. Interact with it.

HUI+ (Hermes Interactive UI+; HUI+ is the name under the app icon) is a mobile, web and desktop app for your own Hermes Agent. Hermes answers with things you can act on: tick a checklist, pick an option, compare products, fill in a form, rank, vote. Each tap goes back to Hermes as the next message, and the conversation continues from there. When Hermes wants to run a command, you approve or deny it from your phone; meanwhile you watch every tool step live, or leave the app while Hermes keeps working.

• Who it is for: people who already run Hermes Agent and talk to it through Telegram or the terminal today.
• What you need: your own Hermes Agent (v0.21 or newer) and a small bridge that you run next to it (npx hermes-ui-plus-bridge setup). There is no hosted service and no account. See Quick start.
• Where it runs: Android (APK), web app (PWA, also on iPhone/iPad), macOS (signed and notarized) and Linux (alpha). Downloads: GitHub Releases.

Status: alpha (0.1). Expect rough edges; see Known limitations. Hermes Interactive UI+ (Hermes Interactive UI Plus) is an unofficial community client. It is not affiliated with, endorsed by, or supported by Nous Research.

Quick start

About 10 minutes if Hermes already runs. Just looking? Install the Android or desktop app and start the demo from its welcome screen: recorded answers, no Hermes needed.

Set up with your agent

Hermes can run shell commands, so it can set up its own bridge. Paste this prompt into a direct chat with your Hermes (Telegram, Hermes CLI) or into a coding agent on the machine where Hermes runs (Claude Code, Codex). It checks the prerequisites, asks before anything risky, stays on your tailnet and hands you the pair link. Prefer doing it by hand? Follow the steps below. Variants and details: docs/SETUP-WITH-AGENT.md.

Set up the Hermes UI+ bridge on this machine (the one that runs my Hermes Agent) so I can pair the HUI+ app. Docs: https://github.com/robbyczgw-cla/hermes-ui-plus/blob/main/docs/SETUP-WITH-AGENT.md

1. Check first, change nothing: `node --version` (22 or newer), Hermes home (`$HERMES_HOME` or `~/.hermes`), `tailscale status`. If something is missing, stop and tell me what and how to get it. Do not guess.
2. Preview: `npx -y hermes-ui-plus-bridge@latest setup --dry-run --json`. Summarize the plan: Hermes API server, skill, env file, service, Tailscale URL, warnings.
3. If the Hermes API server is off, show me the snippet and restart command from the report and wait. Do not edit Hermes' config or restart Hermes yourself (if you are Hermes, a restart ends this chat).
4. After my OK: `npx -y hermes-ui-plus-bridge@latest setup --yes --json` (add `--no-pair` if this is not a private chat with me). If it says a system service needs a global install, ask me before `npm install -g hermes-ui-plus-bridge`.
5. Verify: the report has "ok": true, `curl -s http://127.0.0.1:8790/health` answers, `tailscale serve status` lists the bridge.
6. Send me the "pair.link" from the report. It carries a one-time code that expires after 1 hour, so do not open it yourself. With `--no-pair`, give me this command for my own terminal instead; it shows a QR code: `npx hermes-ui-plus-bridge devices add "Phone" --env-file <env file>`.
7. Finally list what was installed and where (skill, env file, service, `tailscale serve`) and how to undo each part, e.g. stop and disable the service, `tailscale serve --https=8790 off`, delete the env file and the skill, restore a skill backup from `~/.hermes/skill-backups/`.

Rules:
- Tailnet or LAN only: never `tailscale funnel`, port forwarding or a public address for the bridge or the Hermes API.
- Never print, log or paste API keys or device tokens (the report masks them). Only the one-time pair link may go to me.
- Ask before installing system packages, changing Hermes' config or restarting Hermes.
- If a step fails, stop and show me the error with secrets removed.

Before you start

• Hermes Agent v0.21 or newer on a machine you control. Tested with Hermes v0.22.0; see Hermes compatibility.
• Node.js 22+ on that machine, for the bridge (check with node --version). The Hermes installer brings its own private Node.js, which is not on your PATH, so npx may be missing. Distribution packages are often too old (Ubuntu 24.04's nodejs is version 18): install a current LTS from nodejs.org, the NodeSource packages or nvm. Docker works too, but there is no prebuilt image in 0.1: you build it from a checkout (docs/SELF-HOSTING.md).
• A private network path from your phone to that machine. Tailscale is strongly recommended (HTTPS, nothing exposed to the internet). No Tailscale? For the Android app a LAN address over plain HTTP is enough for a test (LAN only); a first test of the web app in a browser on the bridge machine itself needs neither (docs/WEB-APP.md).

1. Turn on the Hermes API server

Once. The first two lines only add what is missing, so they are safe to run again (Hermes' own setup may already have written a key; a second API_SERVER_KEY line would silently replace it). Then start the Hermes gateway, which serves the API:

grep -qs '^API_SERVER_ENABLED=true' ~/.hermes/.env || echo 'API_SERVER_ENABLED=true' >> ~/.hermes/.env
grep -qs '^API_SERVER_KEY=.' ~/.hermes/.env || echo "API_SERVER_KEY=$(openssl rand -hex 32)" >> ~/.hermes/.env
hermes gateway install              # background service (systemd/launchd); in Docker or WSL: hermes gateway run
hermes gateway status
curl http://127.0.0.1:8642/health   # should answer {"status": "ok", ...}

Gateway already running? It reads the settings only at start. As a service: hermes gateway restart. Started with hermes gateway run in a terminal: stop it with Ctrl+C and start it again. hermes gateway restart only manages the service; it can stop a gateway that runs in a terminal without starting it again, so check with hermes gateway status.

Hermes runs in Docker? There ~/.hermes belongs to the container's user, so edit the file through the container, and let the API server listen on the container network (API_SERVER_HOST=0.0.0.0; do not publish port 8642). Details and a compose file for Hermes and the bridge together: Hermes runs in Docker too.

docker exec <hermes-container> sh -c 'f=/opt/data/.env
grep -q "^API_SERVER_ENABLED=true" $f || echo API_SERVER_ENABLED=true >> $f
grep -q "^API_SERVER_HOST=0.0.0.0" $f || echo API_SERVER_HOST=0.0.0.0 >> $f
grep -q "^API_SERVER_KEY=." $f || echo "API_SERVER_KEY=$(od -An -N32 -tx1 /dev/urandom | tr -d " \n")" >> $f'
docker restart <hermes-container>

2. Set up the bridge

On the machine that runs Hermes:

npx hermes-ui-plus-bridge setup

The wizard checks Hermes (home directory, API server, version), installs the hermes-ui skill, offers Web Push, writes the bridge settings, installs a service (systemd, or launchd on macOS; inside a container it prints the start command instead), publishes the bridge on your tailnet with tailscale serve, and finally prints a QR code and pair link. Without Tailscale it prints no QR code; instead it tells you where to set the address your phone can reach (BRIDGE_PUBLIC_URL) and how to get a new pair link afterwards.

• By default the bridge is a pure pass-through to Hermes: no provider keys are asked for. Optional direct-provider extras (LLM router, chat titles, image search, voice) are opt-in with setup --extras and call providers from the bridge, outside Hermes; see docs/BRIDGE.md.
• Preview first: npx hermes-ui-plus-bridge setup --dry-run. Re-run the wizard any time to update; it changes things in place.
• It never edits Hermes' config without asking and never restarts Hermes. If the Hermes API server is off, it shows the exact config snippet and restart command.
• Let an agent do it: see Set up with your agent above; more prompts in docs/SETUP-WITH-AGENT.md.
• Docker, manual setup and LAN-only use: docs/SELF-HOSTING.md. The skill alone: hermes-skill/INSTALL.md.

3. Install the app and pair it

• Android: install the APK (Install on Android), open the app and choose Scan QR code.
• Web app (PWA), also iPhone and iPad: unpack the web bundle next to the bridge and open the pair link: docs/WEB-APP.md. On iPhone/iPad, Add to Home Screen afterwards; the native iOS app is not published yet.
• macOS / Linux: download the app from GitHub Releases (Platforms) and paste the pair link.

A QR code or pair link carries a one-time pairing code, not a token: the app exchanges it for its own revocable device token the first time it connects. The code works once and expires after one hour if unused. Never share a screenshot of a QR code. A new pair link at any time: npx hermes-ui-plus-bridge devices add "Phone".

Warning: do not expose the bridge or the Hermes API server to the public internet. Hermes can run terminal and file tools, and anyone with access can use them. Do not use port forwarding or tailscale funnel. Stay on your tailnet or your trusted LAN.

Features

• Act on answers instead of just reading them. 51 native answer components, 25 of them interactive: checklists you tick, choices and decisions you make, forms and calculators you fill in, products and places you compare, polls, rankings and scales, quizzes, flashcards and vocabulary trainers, timers, workouts, study plans, and paths (2-6 ways or variants with a verdict badge, optionally one to choose). Every check, vote, choice or slider value goes back to Hermes as the next message, so you pick the next step with a tap instead of typing it; the state is kept per conversation. The others present: tables, charts (bar, line, pie, radar, gauge, heatmap and more), stats, comparisons, steps, timelines, mind maps and blocks (an architecture at a glance: boxes in up to three columns with an optional shared base layer). Hermes picks the component; the count includes layout and text nodes, and sandboxed HTML widgets come on top.
• Coding views. After Hermes edits files or runs commands, the answer can show a native diff (file by file, word-level highlight, split view on wide screens, comments on single lines that go back to Hermes as one message), a terminal view with the real output, exit code and duration, and a changes list with a review sheet.
• Share in and out. Share to HUI+ from other apps (links, text, images, files; Android and the web app, iOS prepared) opens a small sheet and sends nothing until you tap Send. Any answer can be shared as an image, with what you ticked or picked.
• Approvals. When Hermes asks before running a command, you see the command, Hermes' reason and an estimated risk, and answer in the app: allow once, for this task, always, or deny. The web app (PWA) can also notify you through Web Push while it is closed. Android has no remote push in 0.1: no notification while the app is closed (Known limitations).

Choose a path	Tick a checklist	Approve a command

• Streaming chat with Markdown, rendered progressively while Hermes writes, plus a tool-call timeline that shows what ran and how long it took. Switching between chats is instant (transcripts are cached and fetched ahead), you can press Send while attachments are still uploading (the message shows at once and the turn starts when the uploads are done), and the drawer loads older Hermes chats at its end, so older app chats are reachable on a new device. Settings → Chat → Chats chooses whether the drawer lists this app's chats from all your devices (default) or only those created on this device; nothing is deleted either way.
• Router. The UI-Bridge decides per message whether a plain answer or an interactive component fits best, so short questions stay short. It works rule-based out of the box and can use an LLM if you configure one.
• Hermes profiles (bots). If your Hermes has profiles (hermes profile create <name>: own model, memory and skills), each chat can talk to one of them: pick it in the model menu's "Bot" section. Session sync, approvals and push open the chat of the right bot. With the bridge the bots are listed automatically; without profiles nothing changes (no "Bot" section). On Hermes v0.22 put the same API_SERVER_KEY into every profile's own .env.
• Schnellfrage (quick questions, ⚡). One-off questions answered in about two seconds by a fast model of your Hermes, without the agent (no memory, tools or live data), in a local quick thread; "Mit Hermes weitermachen" hands the answer to a normal chat. Needs the optional Hermes plugin hermes-ui-plus (docs/HERMES-PLUGIN.md); without it the ⚡ entry is simply not shown.
• Slash commands (/new, /model, /reasoning, /retry, /stop, /approve, /skills, /usage, /export and more) with a searchable palette, in English, German and Spanish.
• Voice. Dictation (tap to start and stop, or hold to talk; recording starts on touch-down) and read-aloud: on-device speech recognition and voices, speech providers configured on your bridge, or providers you add in the app with your own key. With "Read replies aloud automatically" on, reading starts with the first complete sentences while the answer is still streaming.
• Images and files. Attach photos and documents; images in answers carry their source. Product and place photos from Hermes' answers load through your bridge's image proxy without a tap; other unknown hosts are tap-to-load. Places, food and sights also get photos from Wikipedia. Product cards show a photo only when Hermes returns one or the bridge has an image search key (setup --extras, Serper or Brave); otherwise they show a neutral icon rather than a possibly wrong photo.
• Accessibility. Screen reader labels and state, AA contrast in every theme, layouts that hold at large text sizes and full keyboard use on the web. Tested with automated audits and in a browser; not yet reviewed with TalkBack or VoiceOver on a device.
• Sandboxed HTML widgets for custom visuals, with no access to your data or device.
• Multi-platform. One codebase for Android, web (PWA), macOS and Linux (Tauri) and iOS. See Platforms for what you can install today.
• Local-first. Conversations are stored on your device. No accounts, no telemetry.

How it works

• The app talks only to your bridge, so it never sees your Hermes API key. "Connect without the bridge" in onboarding is optional: the app then uses the API key directly and has none of the bridge's features.
• The UI-Bridge (bridge/) is a small open-source Node service you run next to Hermes. It holds the API key, authenticates your devices, routes presentation, handles uploads, voice and push, and pairs new devices by QR code. Why it exists and how it is secured: docs/BRIDGE.md.
• The skill (hermes-skill/hermes-ui/) teaches Hermes the answer protocol. It only loads for sessions from this app, so Telegram, cron and other clients are unaffected.

Platforms

macOS app. The same UI in a native shell: translucent sidebar and unified title bar, menu bar and keyboard shortcuts (new chat, search chats, find in chat, stop, switch chats), a native right-click menu on answers, dock badge for unread answers and a dock menu with recent chats, notifications for finished answers and approvals (with Allow once / Deny buttons, no need to open the window), open at login, a menu-bar-only mode, an optional Touch ID lock, and files by drag and drop, onto the dock icon or paste. Global shortcut: Option+Space. Notifications come from the running app (including while its window is closed); there is no push to a Mac that is off or has quit the app.

Install the web app: download hermes-ui-plus-web-<version>.tar.gz, unpack it on the bridge machine, run npx hermes-ui-plus-bridge setup --web-dir <folder> and open the pair link. Step by step: docs/WEB-APP.md.

Install on Android

The APK runs on 64-bit ARM (arm64-v8a) devices with Android 7.0 or newer, which covers practically every current phone and tablet. There is no 32-bit or x86 build: the APK does not start on x86 Android emulators or x86 ChromeOS devices, not even with their ARM translation (it closes right away with "HUI+ keeps stopping"). Use the web app there.

1. Download hermes-ui-plus-<version>.apk and hermes-ui-plus-<version>.apk.sha256 from GitHub Releases.
2. Verify the download: sha256sum -c hermes-ui-plus-<version>.apk.sha256 in the download folder should print OK.
3. Optionally check the signing certificate: apksigner verify --print-certs <file>.apk should show the certificate SHA-256 digest 17:9B:2D:B4:99:6E:C6:BF:8D:B5:43:46:11:98:5E:38:AE:5E:21:A0:3E:A0:12:55:8B:A6:A6:5A:44:12:6E:06 (apksigner prints it without colons, in lower case).
4. Open the APK on the phone and allow installing from your browser or file manager when Android asks.

To get updates automatically, add https://github.com/robbyczgw-cla/hermes-ui-plus to Obtainium. Alpha and beta versions are published as GitHub pre-releases, which Obtainium skips by default: turn on Include prereleases in the app's settings in Obtainium. The certificate stays the same across releases, so updates install over the existing app.

To build from source, see docs/BUILD.md.

Hermes compatibility

The app is built against the Hermes Agent API server (v0.21 or newer) and tested with Hermes v0.22.0. Two known Hermes issues affect it; neither is caused by this app, and both have upstream fixes in review:

• /skills fails on unpatched Hermes 0.21.5 to 0.22.2. GET /v1/skills answers HTTP 500 there (upstream issue #120831, fix in PR #124861). The app recognises that error, tells you it is a Hermes bug and shows the server's message under "Details"; the skills themselves still work in chats.
• Claude answers can arrive in one piece on unpatched Hermes. With the Claude subscription plugin (a provider that Hermes runs as an external process), Hermes does not stream the answer: it sends the finished text in a single chunk at the end. Upstream PR #124566 lets such providers stream; the plugin has to opt in as well. Any API client sees this, including this app: the answer appears all at once instead of word by word. The app has no workaround for it. Providers that Hermes calls directly (not as an external process) are not affected.

Known limitations (alpha)

• iOS: web app (PWA) only. The native app is prepared for TestFlight / App Store, but nothing is submitted yet.
• Desktop: the macOS app is Apple Silicon only. The Linux AppImage / .deb is an alpha: x86_64 only, not signed, no auto-update, needs glibc 2.35 or newer, and the tray icon and Alt+Space shortcut depend on the desktop environment (details in desktop/README.md).
• No app-store builds (Google Play, App Store). Android installs from the APK on GitHub Releases.
• No remote push on Android in 0.1. The APK from GitHub Releases contains no Firebase (FCM) setup. While an answer is running, the app's keep-alive service shows its notification and keeps the answer coming; but a notification while the app is closed (for example "approval needed") is not available on Android in 0.1. Planned: UnifiedPush / ntfy.
• Web Push works in the web app (PWA), including the iPhone/iPad home-screen app (iOS 16.4+). It needs the bridge with Web Push keys (the setup wizard offers them). The macOS app shows native notifications (also with approval buttons) while it is running; it does not use Web Push.
• Schnellfrage is experimental: it needs the hermes-ui-plus Hermes plugin, which calls one internal Hermes function (call_llm) and may need an update after a Hermes release. Chats never depend on it. In a bot (Hermes profile) chat ⚡ is not offered: the plugin answers for the whole gateway, not per profile.
• Slash commands are handled by the app. Hermes' API server does not interpret them, so an unknown command is sent as plain text.
• Hermes issues (/skills on 0.21.5 to 0.22.2, Claude answers arriving in one piece): see Hermes compatibility.
• Approvals: in Hermes "smart" approval mode Hermes auto-approves most commands, so approval cards appear only when Hermes really asks.
• Plain http:// works for the Android app. Over plain http:// on the LAN the web app runs only in a browser tab: installing it, offline use and push need HTTPS (for example tailscale serve). http://127.0.0.1 on the bridge machine itself counts as secure.

Privacy

• No telemetry, no accounts. The app contains no analytics or crash-reporting SDK, and the developers run no servers that your data touches.
• Your messages go from your device to your bridge, then to your Hermes, and from there to the model providers you configured in Hermes. Nowhere else.
• Web Push (web app) goes through your browser vendor's push service only if you enable it; the payload is encrypted and message previews are off by default.

Full policy: PRIVACY.md. Threat model and how to report vulnerabilities: SECURITY.md.

Documentation

• docs/BRIDGE.md: what the bridge does, why it is needed, security model, where data goes
• docs/SELF-HOSTING.md: bridge setup, Tailscale, device tokens, push, updating, troubleshooting
• docs/WEB-APP.md: installing the web app (PWA) and adding it to the home screen
• docs/SETUP-WITH-AGENT.md: copy-paste prompts so Hermes, Claude Code or Codex set it up for you
• bridge/README.md: bridge reference (CLI options, environment variables)
• docs/SPEC.md: the answer protocol and architecture
• docs/ROUTER.md: router and the complete configuration reference
• docs/BUILD.md: building the Android, iOS, web and desktop apps
• docs/IOS.md: iOS status (web app now), TestFlight / App Store preparation
• CONTRIBUTING.md, CHANGELOG.md

Credits

CopilotKit OpenIntelligentUI (MIT) inspired the interactive answer approach and parts of the sandbox renderer. Thanks to Nous Research for Hermes Agent. Other third-party notices are in NOTICE.md.

License

See LICENSE. Third-party notices are in NOTICE.md.