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.

Staying up to date (sideload): the app checks GitHub for a newer release on cold start (at most once every 6 hours) and shows a dismissable banner when you're behind. Tapping Update opens the next APK in your browser so Android's Downloads notification hands it to the system installer — no second app required. You can also trigger a check manually under Settings → About → Updates. Google Play installs get auto-updates through the Play Store and don't show this banner.

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.

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.

What's new in v0.6.0

• Connect from anywhere — multi-endpoint pairing with first-class Tailscale support; plug in any VPN or reverse proxy mode. See docs/remote-access.md.
• Multi-Connection support — pair with multiple Hermes servers (home + work, dev + prod, etc.) and switch in one tap from the Chat top bar. Each Connection keeps its own sessions, personalities, profiles, and relay state; theme and safety preferences stay global. Existing installs migrate transparently.
• Agent Profiles — the relay auto-discovers upstream Hermes profiles at ~/.hermes/profiles/*/ and the phone overlays the selected profile's model + SOUL.md on chat turns. Ephemeral, chat-only, clears on Connection switch. Gated by RELAY_PROFILE_DISCOVERY_ENABLED (default on).
• Consolidated agent sheet — Profile + Personality selection and per-session analytics now live in one scrollable bottom sheet opened from the Chat top-bar agent name.

See the changelog for the full list.

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
• Multi-Connection + agent profiles — Pair with multiple Hermes servers and switch targets from the top bar; select an upstream-discovered agent profile to overlay model + SOUL.md on chat turns. Three-layer model: Connection (server) → Profile (agent directory) → Personality (prompt preset)
• 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

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

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 (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

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