Codename-11/hermes-relay

Runs on your machine. Lives on your devices.
A native Android companion for your Hermes agent — streaming chat, hands-free voice, and full agent management. Plus a single-binary CLI that gives the agent hands on any machine you pair.

English · 简体中文
Documentation · Releases · Changelog · Hermes Agent

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, and the full Hermes dashboard (models, keys, skills, profiles), rebuilt native. On sideload builds, the agent can read your screen and act on it.
• ⌨️ 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, and voice need no plugin. Add the optional relay only when you want terminal, phone control, 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, or the realtime voice engine:

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

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

Cold start	Streaming chat	Hands-free voice	Session history
App themes	Manage your agent	Connections & routes	Avatars & skins

Simplified Chinese

设置 — 全面汉化

管理 — 仪表盘汉化

导航菜单 — 简体中文

The Android app ships complete AI-assisted catalogs for Deutsch, Español, 日本語, Português (Brasil), and 简体中文. Choose a language from Settings → Appearance → Language; translation status and fluent review are tracked independently so community corrections remain easy to contribute.

_{▶ Watch the demo on the docs site}

Features

Android

• Streaming chat — rides vanilla Hermes, preferring the dashboard gateway (/api/ws, live thinking) when signed in to Manage and falling back to API-server SSE otherwise, with live markdown, tool-call cards, session history, a searchable command palette, file attachments, quote-in-reply, conversation share, and send-while-streaming queuing.
• Manage your agent — the full Hermes dashboard, native: switch models from your provider catalog, manage keys (write-only, masked, rate-limited reveal), create and edit profiles including SOUL.md, and browse/install/update skills. One dashboard sign-in covers it all.
• Hands-free voice — talk on a vanilla install: speech rides your server's configured providers, unlocked by the same Manage sign-in. Relay-paired setups add per-profile voice and an opt-in provider-native Realtime Agent with background task handoff.
• Works away from home — add a Tailscale or public URL and the app roams automatically (LAN at home, fallback elsewhere). An unreachable server gets a diagnosis, not just a red dot.
• Multi-Connection + profiles — pair multiple Hermes servers (home + work, dev + prod) and switch in one tap; overlay a profile's model + SOUL.md per chat.
• Phone control (bridge) — with Relay paired, the agent reads the screen and acts: tap, type, swipe, scroll, screenshots, clipboard, media keys, batched macros. Guarded by per-app blocklist (banking/2FA blocked by default), destructive-verb confirmation, idle auto-disable, and a full activity log.
• Notification companion — opt-in access so the agent can triage, summarize, and route incoming notifications.
• Security & pairing — QR pairing, Android Keystore session storage (StrongBox-preferred), TOFU cert pinning, per-channel time-bound grants, user-chosen session TTL.
• Stats for Nerds — local-only analytics: TTFT, token usage, stream health, peak-time charts.

Sideload builds add direct SMS, contact search, one-tap dialing, and location awareness — handy for fully hands-free intents like "text Sam I'll be 10 minutes late." See Release tracks.

Hands on any machine — the Hermes-Relay CLI _(alpha)

Alpha. Self-contained CLI binaries ship for Windows x64, Linux x64, and macOS x64/arm64 — no Node required. Windows also has an optional native, menu-only systray. Assets are unsigned during the experimental phase, so SmartScreen / Gatekeeper warnings are expected.

The agent's brain stays on the host; the CLI lets it call tools on your machine over the same WSS relay — read_file, write_file, terminal, search_files, screenshot, clipboard, open_in_editor, and more — behind a one-time consent gate, interactive diff approval for patches, and a --no-tools kill-switch.

irm https://raw.githubusercontent.com/Codename-11/hermes-relay/main/desktop/scripts/install.ps1 | iex

hermes-relay pair --remote ws://<host>:8767   # once
hermes-relay daemon start                      # background tool router — agent reaches you anytime
hermes-relay update                            # self-update via GitHub Releases

It pairs against the same relay and credential store as the Android app — pair once from either, both work. Tagged on the desktop-v* release track, with historical releases still visible under cli-v*.

On Windows, the default installer adds the optional right-click-only systray: no dashboard or app window, just TUI launch, User/Administrator-aware daemon controls, pairing, local grant review, audit, diagnostics, logs, desktop-use status/cancellation, sign-in startup, and emergency stop.

• Docs: CLI guide · desktop/README.md
• AI-agent setup recipe: /hermes-relay-desktop-setup

How It Works

Phone        (HTTP/WSS) --> Hermes Dashboard  (:9119)   [chat gateway, manage, vanilla voice]
Phone        (HTTP/SSE) --> Hermes API Server (:8642)   [chat fallback, sessions, runs]
Phone        (WSS/HTTP) --> Relay             (:8767)   [terminal, bridge, media, relay voice, sessions]
CLI          (WSS)      --> Relay             (:8767)   [machine tools, tui, terminal]

Chat prefers the Hermes dashboard gateway when Manage auth is ready, then falls back to the upstream API server SSE path with the API key. Manage and Vanilla Hermes voice ride the Hermes dashboard with its own one-time sign-in, so a vanilla install needs no plugin for either. The optional relay on :8767 adds the power surfaces: terminal, bridge phone control, media handoff, machine tools, and relay-side voice, which is preferred automatically when paired. One QR can configure API, dashboard, and relay routes without merging their auth models.

Documentation

You are helping me install and maintain Hermes-Relay (https://github.com/Codename-11/hermes-relay) — a native Android client + a CLI + a 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 server-plugin install one-liner: `curl -fsSL https://raw.githubusercontent.com/Codename-11/hermes-relay/main/install.sh | bash`
- Connecting my phone by Vanilla Hermes API URL/key first, then optionally pairing Relay via `hermes pair` or `/hermes-relay-pair` for power tools; OR pairing my laptop via the Hermes-Relay CLI (`irm https://raw.githubusercontent.com/Codename-11/hermes-relay/main/desktop/scripts/install.ps1 | iex` on Windows, then `hermes-relay pair --remote ws://<host>:8767`)
- Verifying with `hermes-status` (server) or `hermes-relay doctor` (CLI)

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.

Development

# Android: open the repo root in Android Studio, wait for Gradle sync, Run (Shift+F10).
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 the relay server (dev, no TLS)

Tech Stack

hermes-relay/
├── app/                       # Android app (Kotlin + Jetpack Compose)
├── desktop/                   # Hermes-Relay CLI thin-client (TS + Bun-compiled binary)
├── relay_server/              # WSS server (Python + aiohttp; thin shim → plugin/relay)
├── plugin/                    # Hermes agent plugin
│   ├── relay/                 #   - canonical relay (server.py, channels/, media, voice, machine tools)
│   ├── tools/                 #   - android_* bridge + desktop_* tool handlers
│   └── pair.py                #   - QR pairing CLI + multi-endpoint payload builder
├── skills/devops/             # Hermes agent skills (pairing, self-setup, CLI setup recipes)
├── user-docs/                 # VitePress documentation site
├── docs/                      # Spec, decisions, security
├── scripts/                   # Dev helper scripts
├── .github/workflows/         # CI + release pipelines (ci-android / ci-plugin / ci-desktop)
└── gradle/                    # Wrapper (8.13) + version catalog

hermes relay start --no-ssl          # if you installed the plugin
python -m plugin.relay --no-ssl      # or from a repo checkout

# Docker:
docker build -t hermes-relay relay_server/ && docker run -d --network host --name hermes-relay hermes-relay

# Live-edit the plugin against a local Hermes:
ln -s "$PWD/plugin" ~/.hermes/plugins/hermes-relay

Built for 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