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:

1. Download the file ending in -sideload-release.apk from the latest release — that's the full-featured "Hermes Dev" build. (Skip any .aab file — those are the Google Play bundle format and won't install directly.)
2. On your phone: Settings → Apps → Special app access → Install unknown apps and allow your browser (first time only).
3. Open the APK from your downloads and tap Install.
4. Optionally verify integrity against SHA256SUMS.txt from the same release (sha256sum on macOS/Linux, Get-FileHash -Algorithm SHA256 on 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-pair and the hermes-relay-pair skill renders the QR inline. Shortest path if you're already chatting with the agent.
• From a shell: hermes-pair (dashed) — a thin wrapper around python -m plugin.pair in 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.

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
Terminal	Secure remote shell via tmux	Phase 2
Bridge	Agent controls the phone — taps, types, screenshots	Phase 3

Features

• Streaming chat — Direct SSE to the Hermes API Server with real-time markdown rendering
• Voice mode — Real-time voice conversation via the relay; sphere listens with you, 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)
• Smooth auto-scroll — Live-follow streaming responses with a "scrolled up to read" pause/resume gesture
• Session management — Create, switch, rename, delete chat sessions
• Tool visualization — See agent tool calls as they execute (compact or detailed cards)
• Personalities — Switch between agent personalities with a picker
• Slash commands — 29+ gateway commands, searchable command palette
• File attachments — Send images, documents, any file type
• Message queuing — Send messages while the agent is still streaming
• Analytics — Stats for Nerds with TTFT, token usage, stream health
• Security — Encrypted local storage (AES-256-GCM), HTTPS enforced
• QR pairing — Scan a QR code to auto-configure your server connection

Getting Started

1. Install the app from the link above
2. Enter your Hermes server URL (e.g. http://192.168.1.100:8642) during onboarding
3. 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

1. File > Open the repo root in Android Studio
2. Wait for Gradle sync
3. 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 (14 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