hermes-relay

What it is

Hermes-Relay puts your Hermes agent on the devices you actually carry. The brain stays on your own machine — Hermes-Relay is how you reach it.

• 📱 Android app — streaming chat, hands-free voice, native plugin pages, and the full Hermes dashboard (models, keys, skills, profiles), rebuilt native. Add a floating Petdex companion or optionally make Hermes your Android assistant; sideload builds can also let the agent read and act on your screen.
• ⌨️ Hermes-Relay CLI (beta) — a single binary that gives the agent hands on any machine you pair: files, terminal, search, screenshots — consent-gated.

A vanilla hermes-agent install is enough for the upstream standard path: chat, management, voice, inbound files, Petdex, and ordinary installed-plugin pages. The Hermes-Relay plugin is optional for that base but encouraged for the complete current experience: Terminal/TUI, notifications, desktop tools, enhanced voice, Relay sessions, page drafts, optional Device Control, and media compatibility or metadata. Hermes-Relay prefers compatible upstream surfaces as they become available instead of keeping duplicate extension paths. Connect Hermes first, then grant Hermes-Relay separately; the same one-time invite contract pairs Android or the Desktop CLI.

Quick Start (Android)

Install → connect → talk, in about two minutes.

1 · Install the app

• Google Play (easiest — auto-updates) — install from Google Play. Chat, voice, sessions, Manage, and inbound files work with standard Hermes; pairing the Hermes-Relay plugin adds Terminal/TUI, notifications, Relay sessions, and media enhancements.
• APK (full phone-control feature set) — download the file ending in -sideload-release.apk from the newest android-v* release on GitHub Releases and open it (allow your browser to install unknown apps the first time). Integrity verification, signing fingerprint, and per-build details are in the Sideload guide.

Sideload builds check GitHub for updates and show a one-tap banner when you're behind; Play builds update through the Store. See Release tracks for the capability matrix.

2 · Have the Hermes Dashboard running

The normal Android connection uses the upstream Hermes Dashboard/Gateway for chat, sign-in, sessions, Manage, voice, and inbound files. Installing Hermes and choosing a provider is vanilla Hermes setup:

hermes setup --portal   # install / log in / pick a provider — skip if already done
hermes dashboard       # start the standard Dashboard/Gateway surface

Make the dashboard reachable from your phone over a trusted LAN, Tailscale, or an HTTPS reverse proxy. The full walkthrough covers Windows, remote access, and dashboard authentication. You do not need to enable the separate API server or invent an API key for the standard path.

Start on a trusted LAN. For away-from-home access, Tailscale is the recommended path. Secure Link, public TLS, and experimental routing options are covered in the remote-access guide.

3 · Connect and talk

Use Find Hermes on LAN or enter the Dashboard address manually (conventionally http://<host>:9119). Sign in through the Dashboard's configured provider when prompted. The app probes the available upstream capabilities and finishes with a connection summary.

If the Relay Dashboard page is already installed, Connect mobile app offers the same standard connection as a tokenless QR. It contains only the Dashboard address and does not install, enable, or pair Relay.

The separate API server can be discovered automatically or added later under Advanced as a chat fallback or for a headless compatibility setup. Its API key is requested only when that optional endpoint is configured. Existing API-first setup QRs remain importable.

The wizard probes everything and finishes with a capability card:

One dashboard sign-in unlocks Chat, Manage, sessions, and standard voice. That's the whole Vanilla Hermes setup.

Going places? Add the Dashboard's Tailscale address — for example http://100.x.y.z:9119 or a separately published https://host.ts.net URL — under Settings → Gateways → Routes. Android tests it as a Dashboard route; no API server or API key is required. The app uses LAN at home and switches routes automatically when you leave. See Remote access.

4 · Recommended: pair Relay for the complete experience

Install Relay for Terminal/TUI, notifications, desktop tools, enhanced voice, Relay sessions, approval-gated page drafts, optional Device Control, and media compatibility or sensitivity metadata:

hermes plugins install Codename-11/hermes-relay/plugin --enable
hermes relay doctor
hermes relay start --no-ssl

Use --no-ssl only on a trusted LAN or VPN. Use the remote-access guide before exposing any Hermes surface beyond that network.

Refresh or restart the Dashboard/Gateway, open Relay → Pair new device, and scan the one-time QR from Android Settings → Gateways → Access → Pair Relay. Leave mode on Auto for the recommended route discovery. The same dialog shows a copyable invite for Desktop CLI clients:

hermes-relay pair --pair-qr "hermes-relay://pair?payload=…" --grant-tools

As alternatives, hermes pair renders the same Android QR and pasteable invite in a terminal, while URL + six-character code and --register-code remain manual fallbacks when QR or clipboard transfer is unavailable.

Next: Android + Hermes-Relay Quick Start · Desktop CLI pairing · server, TLS, legacy install, and uninstall reference

Requirements: Android 8.0+ (SDK 26) · current upstream hermes-agent with the Dashboard/Gateway enabled · Python 3.11+ when installing the Hermes-Relay plugin. Direct API is optional; the Hermes-Relay plugin is encouraged for the complete experience.

Screenshots