Bailey Dixon
d7e5fc87f8
The earlier dialog hardcoded window.location.hostname + port 8767 +
tls=false, which only worked for plain LAN deploys. Behind Traefik
or similar reverse proxies, the phone needs a completely different
endpoint than the dashboard URL.
Now:
* First open infers sensible defaults from the dashboard URL —
https://hermes.axiom-labs.dev defaults to the dashboard hostname
with TLS enabled on :443; plain http defaults to port 8767 with
TLS disabled.
* "Edit" reveals a Host / Port / TLS form with a live wss:// preview.
* Values persist in localStorage (hermes-relay-pair-{host,port,tls})
so subsequent opens skip the form.
* Toggling TLS auto-updates the default port (80↔443, 8767↔443)
while preserving any non-default value the operator typed in.
* Errors surface an "Edit pair URL" shortcut so a misconfigured
host can be fixed without re-navigating.
RelayManagement no longer passes host/port/tls props — the dialog
owns its config end-to-end.
Hermes-Relay
Native Android client for the Hermes agent platform.
Chat, control, and connect — one app for your AI agent.
Documentation · Releases · Changelog · Hermes Agent
Quick Start
Two steps: install the Android app on your phone, then install the plugin on your Hermes server.
1. Install the Android app
- Google Play — coming soon (currently on Internal testing)
- APK — download from GitHub Releases
Sideload APK (GitHub Releases)
Prefer not to wait for Google Play? Grab the signed APK directly:
- Download the file ending in
-sideload-release.apkfrom the latest release — that's the full-featured "Hermes Dev" build. (Skip any.aabfile — those are the Google Play bundle format and won't install directly.) - On your phone: Settings → Apps → Special app access → Install unknown apps and allow your browser (first time only).
- Open the APK from your downloads and tap Install.
- Optionally verify integrity against
SHA256SUMS.txtfrom the same release (sha256sumon macOS/Linux,Get-FileHash -Algorithm SHA256on Windows).
Full walkthrough, including signing-certificate fingerprint: Sideload guide.
2. Install the server plugin (one-liner)
On the machine running your Hermes agent:
curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/install.sh | bash
The installer clones Hermes-Relay to ~/.hermes/hermes-relay/ (override with $HERMES_RELAY_HOME), pip install -es the package into the hermes-agent venv, registers the skills/ directory in your ~/.hermes/config.yaml under skills.external_dirs (so updates flow through git pull), symlinks the plugin into ~/.hermes/plugins/hermes-relay, drops a thin hermes-pair shim into ~/.local/bin/, and (optionally) installs a systemd user service for the WSS relay. After restart, pair your phone via either of these equivalent entry points:
- From any Hermes chat surface (CLI, Discord, Telegram, etc.): type
/hermes-relay-pairand thehermes-relay-pairskill renders the QR inline. Shortest path if you're already chatting with the agent. - From a shell:
hermes-pair(dashed) — a thin wrapper aroundpython -m plugin.pairin the hermes-agent venv. Use this in scripts or when you want the raw output. - No camera?
hermes-pair --register-code ABCD12— manual fallback for SSH-only / camera-less setups. Read the 6-char code from the app's Settings → Connection → Manual pairing code (fallback) card, pre-register it on the host with this command, then tap Connect in the app. Composes with--ttl/--grants.
Scan the QR from the Android app's onboarding screen and you're connected. One scan configures both the direct-chat API server and the WSS relay (for terminal/bridge) — if a local relay is running at localhost:8767, the pair command pre-registers a fresh 6-char pairing code with it and embeds the relay URL + code in the same QR. If you only want direct chat, pass --no-relay (or just don't start the relay). Plain-text connection details are always printed alongside the QR so you can copy values by hand if your terminal can't render QR blocks.
Dashboard plugin. If your hermes-agent install has the Dashboard Plugin System (upstream axiom branch), Hermes-Relay ships a plugin at plugin/dashboard/ that surfaces paired devices, bridge command activity, and active inbound-media tokens in the gateway's web UI. It auto-registers through the same ~/.hermes/plugins/hermes-relay symlink created by install.sh — restart the gateway and a "Relay" tab appears. See docs/relay-server.md and user-docs/features/dashboard.md for details.
Updating: hermes-relay-update (shortest path — installed as part of the one-liner) or re-run the same curl … | bash from above. Both are equivalent and fully idempotent: pulls latest main, refreshes the editable install, recreates all three shims, restarts hermes-relay, and prompts before restarting hermes-gateway. Set HERMES_RELAY_RESTART_GATEWAY=1 to opt into the gateway restart non-interactively. For routine plugin/skill updates without restarting anything, a plain cd ~/.hermes/hermes-relay && git pull is enough — the editable install picks up the new code on next process start.
Uninstalling: bash ~/.hermes/hermes-relay/uninstall.sh reverses every install step in the opposite order. Idempotent, never touches state shared with other Hermes tools (.env, sessions DB, hermes-agent venv core). Flags: --dry-run, --keep-clone, --remove-secret. Or pull the script via curl if you've already removed the clone.
Requirements: Android 8.0+ (SDK 26), hermes-agent v0.8.0+, Python 3.11+.
For AI Agents
If you have an AI assistant (Claude, GPT, etc.) and want it to install or maintain Hermes-Relay for you, paste the block below into the chat. The agent will fetch the canonical setup recipe from this repo and walk you through it — verification, pairing, troubleshooting included.
You are helping me install and maintain Hermes-Relay (https://github.com/Codename-11/hermes-relay), a native Android client + Python plugin for the Hermes AI agent platform.
Read the canonical setup recipe before acting:
https://raw.githubusercontent.com/Codename-11/hermes-relay/main/skills/devops/hermes-relay-self-setup/SKILL.md
Then guide me through:
- Verifying hermes-agent is already installed (it's a prerequisite — Hermes-Relay is a plugin, not standalone)
- Running the install one-liner: `curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/install.sh | bash`
- Pairing my phone via `hermes-pair` or `/hermes-relay-pair`
- Verifying with `hermes-status`
Always confirm before running shell commands. Never restart hermes-gateway without asking. If any step fails, consult the Troubleshooting section in the SKILL.md and ask me for the exact error.
Already have Hermes-Relay installed? The same recipe is auto-loaded as a Hermes skill — invoke it from any chat with /hermes-relay-self-setup for re-setup, troubleshooting, or "is everything wired correctly?" checks. Single source, two delivery modes (raw URL pre-install + Hermes skill post-install), no drift.
What It Does
Talk to your Hermes agent from anywhere. Direct API streaming, session history, tool visualization — all native on Android.
| Channel | What | Status |
|---|---|---|
| Chat | Stream conversations to Hermes via HTTP/SSE | Available |
| Voice | Real-time voice conversation via relay TTS/STT | Available |
| Bridge | Agent reads the screen and performs UI actions (tap, long-press, drag, type, clipboard, media, macros, events) | Available |
| Terminal | Secure remote shell via tmux | Phase 2 |
Features
- Streaming chat — Direct SSE to the Hermes API Server with real-time markdown rendering, session history, tool-call visualization, personality picker, searchable command palette (29+ gateway commands), file attachments, and send-while-streaming message queuing
- Voice mode — Real-time voice conversation via the relay; the sphere listens with you and performs the agent's reply as it speaks. Uses your server's configured TTS/STT providers (Edge TTS, ElevenLabs, OpenAI, MiniMax, Mistral, NeuTTS / faster-whisper, Groq, OpenAI Whisper)
- Phone control (bridge) — The agent can read what's on screen and act on it — tap, long-press, drag, swipe, scroll, type, and press system keys — plus take screenshots, read/write the clipboard, and control system-wide media playback. Gesture reliability is hardened for dim/idle screens, and a smarter tap-fallback cascade handles apps where labels sit inside non-clickable wrappers
- Screen understanding — Filtered accessibility-tree search, per-node property lookups with stable IDs, cheap screen-hash change detection, and multi-window reads (system overlays, popups, notification shade) so the agent can reason about UI without guessing
- Workflow automation — Batched macro execution for multi-step flows, real-time accessibility event streaming for "wait until something happens" waits, and a raw-Intent escape hatch for apps that expose deep-link actions
- Notification companion — Opt-in notification access so the agent can triage, summarize, and route incoming notifications
- Bridge safety rails — Per-app blocklist (banking, payments, 2FA default-blocked), destructive-verb confirmation modal (send, pay, delete, transfer…), idle auto-disable timer, optional persistent-status overlay, full activity log
- Security & pairing — QR-code pairing, Android Keystore session storage (StrongBox-preferred), TOFU cert pinning, per-channel time-bound grants, user-chosen session TTL
- Analytics — Stats for Nerds with TTFT, token usage, stream health, and peak-time charts
Sideload builds add direct SMS, contact search, one-tap dialing, and location awareness — handy for fully hands-free voice intents like "text Sam I'll be 10 minutes late". See Release tracks for the full sideload capability matrix.
Getting Started
- Install the app from the link above
- Enter your Hermes server URL (e.g.
http://192.168.1.100:8642) during onboarding - Start chatting — the app connects directly to the Hermes API Server
For detailed setup, server configuration, and feature guides, see the full documentation.
How It Works
Phone (HTTP/SSE) --> Hermes API Server (:8642) [chat — direct]
Phone (WSS) --> Relay Server (:8767) [terminal, bridge — future]
Chat connects directly to the Hermes API Server — same pattern used by Open WebUI and other Hermes frontends. The relay server is a separate lightweight Python service for terminal and bridge channels (coming in Phase 2/3).
Documentation
| User Guide | Getting started, features, configuration — start here |
| Architecture | How the app works under the hood |
| API Reference | Hermes API endpoints used by the app |
| Specification | Full spec — protocol, UI, phases, dependencies |
| Architecture Decisions | ADRs — framework, channels, auth, terminal |
| Changelog | Release history |
Development
Quick Start
- File > Open the repo root in Android Studio
- Wait for Gradle sync
- Run (Shift+F10) to deploy to emulator or device
Dev Scripts
scripts/dev.bat build # Build debug APK
scripts/dev.bat release # Build signed release APK
scripts/dev.bat bundle # Build release AAB for Google Play
scripts/dev.bat run # Build + install + launch + logcat
scripts/dev.bat test # Run unit tests
scripts/dev.bat version # Show current version
scripts/dev.bat relay # Start relay server (dev, no TLS)
Repository Structure
hermes-relay/
├── app/ # Android app (Kotlin + Jetpack Compose)
├── relay_server/ # WSS relay server (Python + aiohttp)
├── plugin/ # Hermes agent plugin (18 android_* tools + pair module)
├── skills/ # Hermes agent skills
│ └── devops/
│ └── hermes-relay-pair/ # /hermes-relay-pair slash-command skill
├── user-docs/ # VitePress documentation site
├── docs/ # Spec, decisions, security
├── scripts/ # Dev helper scripts
├── .github/workflows/ # CI + release pipelines
└── gradle/ # Wrapper (8.13) + version catalog
Tech Stack
| Component | Stack |
|---|---|
| Android App | Kotlin 2.0, Jetpack Compose, Material 3, OkHttp |
| Relay Server | Python 3.11+, aiohttp |
| Serialization | kotlinx.serialization |
| Build | AGP 9, Gradle 8.13, JVM toolchain 17 |
| CI/CD | GitHub Actions (lint, build, test, APK artifact) |
| Min SDK | 26 (Android 8.0) / Target SDK 35 |
Relay Server (optional — terminal/bridge only)
hermes relay start --no-ssl # if you installed the plugin
# or from a repo checkout:
python -m plugin.relay --no-ssl
Or with Docker:
docker build -t hermes-relay relay_server/ && docker run -d --network host --name hermes-relay hermes-relay
See docs/relay-server.md for TLS, systemd, and full setup.
Hermes Plugin (for contributors)
End users should install via the one-liner at the top. For local development from a clone:
cp -r plugin ~/.hermes/plugins/hermes-relay
# Or symlink for live edits:
ln -s "$PWD/plugin" ~/.hermes/plugins/hermes-relay
Then restart hermes and run hermes-pair (dashed shell shim) or type /hermes-relay-pair in any Hermes chat surface to verify pairing. The 14 android_* tools register regardless of hermes-agent version. Note: a top-level hermes pair CLI sub-command is not currently exposed — hermes-agent v0.8.0's top-level argparser doesn't yet forward to third-party plugins' register_cli_command() dict. Use the slash command or the dashed shim instead.
Hermes Agent
Hermes-Relay is built for Hermes Agent — an open-source AI agent platform by Nous Research. See the Hermes Agent docs for server setup, gateway configuration, and plugin development.
Found a bug? Let us know!
This is an indie project and every report helps shape where it goes next. If something feels off, broken, or just weird — open an issue. We read every one, and even a one-line "this didn't work on my Pixel 7" is genuinely useful.
Star History
License
MIT — Copyright (c) 2026 Axiom-Labs
Built with the help of Humans and AI Agents
