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 (alpha) — 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 — chat, management, voice, Petdex, and ordinary installed-plugin pages need no Relay plugin. Add the optional Relay only when you want terminal, phone control, agent-created page drafts, or the CLI's tools. Pair once from either surface; both work.

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, Manage, terminal/TUI, media, notifications, and relay sessions.
• 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, and voice. 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.

3 · Connect and talk

Open the app, choose Connect to Hermes, and enter or discover the dashboard address (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.

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 → Connections → 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 · Optional: install Relay for power tools

Install the Relay plugin on the server only when you want Terminal, Bridge phone control, relay sessions, media routes, the realtime voice engine, or approval-gated agent-created plugin-page drafts:

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

Use the legacy installer instead if you also want the systemd user service, shell shims, and the full clone/update workflow:

curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/install.sh | bash

Installed Hermes plugins can expose bounded, host-rendered pages to Android through the authenticated Dashboard without running plugin code on the phone. Relay 1.5.0 additionally supports approval-gated agent-created page drafts. The plugin-manager install owns the plugin code, dashboard tab, CLI commands, and agent tools. hermes relay compat status/install/remove manages only the optional legacy API compatibility hook when an older Hermes build needs it. Scan the QR from the phone's Connections screen — or use hermes pair --register-code ABCD12 with the manual code from Android Settings → Connections → Advanced.

• Plugin-manager uninstall: hermes relay compat remove --all if you installed the optional hook, then hermes plugins remove hermes-relay.
• Legacy installer update: hermes-relay-update (idempotent) — or re-run the install one-liner.
• Legacy installer uninstall: bash ~/.hermes/hermes-relay/uninstall.sh — removes the service, shims, clone, external skill path, editable package, and compat hook. It never touches shared Hermes state. Flags: --dry-run, --keep-clone, --remove-secret.
• Dashboard plugin: installs with the same symlink — restart the gateway and a Relay tab (paired devices, bridge activity, media tokens) appears in the web UI.

Full server setup, TLS, and systemd details: docs/relay-server.md.

Requirements: Android 8.0+ (SDK 26) · current upstream hermes-agent with the Dashboard/Gateway enabled · Python 3.11+ on the server. The API server and Relay are optional.

Screenshots