Codename-11/hermes-relay - AI 开源项目

Hermes-Relay — your Hermes agent, in your pocket

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, 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.

How Hermes-Relay connects — Vanilla Hermes (Chat, Manage, Voice) runs with no plugin; the optional Relay plugin adds Terminal, Bridge, relay voice and desktop tools to the app and CLI; Device Control needs the sideload build.

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.

For plugin-enabled setups, optional Hermes Secure Link presents Relay, API, and Dashboard routes through one pairing-pinned TLS origin. It protects traffic to the paired endpoint while each service keeps its own authentication; it does not provide reachability or independently identify the physical host. You still use LAN routing, Tailscale or another VPN, or an operator-managed public route to reach the listener. Secure Link is off by default and requires a fresh QR pairing after it is enabled. See the remote-access guide.

Hermes Reach is an experimental, advanced outbound-broker route. It remains available for development and self-hosted evaluation, but it is disabled by default, ordered after supported routes, and not recommended for normal remote access. Use Tailscale for the easiest supported remote setup, or a public TLS domain / Direct Secure Link when you want to own the complete network 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:

Line	What it means
Chat	Dashboard/Gateway ready — you can talk
Manage	Models, keys, skills, and profiles are available from the phone
Voice	Speech ready via your server (or one Manage sign-in away)
API fallback	Optional API route available/unavailable
Relay	Optional extensions — fine to leave unpaired

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

_{Voice in chat}	_{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 compact management tray. 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://&lt;host&gt;: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 compact Hermes-Relay CLI UI tray popup for host selection and pairing, connection and daemon state, per-host Ask/Trusted/Full Access, local grant dialogs, authorized-client revocation, activity, settings, and emergency stop. It is a management surface only—chat, TUI, plugins, voice, and agent sessions remain CLI/upstream concerns.

Structured Windows computer control prefers a compatible local CUA Driver runtime for window-targeted background actions and virtual per-session agent cursors. It remains behind Hermes host policy, grants, targeting, audit, and emergency stop; Windows input is an explicit compatibility backend. CUA is not bundled or updated automatically, but the local CLI/UI can explicitly install, check, or update its verified canonical package. It is never exposed as a raw remote tool surface. See the desktop tools guide.

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

How It Works

Phone        (HTTP/WSS) --&gt; Hermes Dashboard  (:9119)   [chat gateway, manage, vanilla voice]
Phone        (HTTP/SSE) --&gt; Hermes API Server (:8642)   [chat fallback, sessions, runs]
Phone        (WSS/HTTP) --&gt; Relay             (:8767)   [terminal, bridge, media, relay voice, sessions]
CLI          (WSS)      --&gt; 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


User Guide	Quick start, features, configuration — start here
Android	Android install + setup + features
Hermes-Relay CLI	Pairing, subcommands, local tool routing
Architecture	How the system works under the hood
API Reference	Hermes API endpoints used by both surfaces
Specification	Full spec — protocol, UI, phases, dependencies
Architecture Decisions	ADRs — framework, channels, auth, terminal
Changelog	Release history (`android-v`, `server-v`, `desktop-v*`; historical prefixes remain immutable)

Install with an AI agent — paste-ready prompt for Claude / GPT
If an AI assistant manages your server, paste this block into its chat and it will fetch the canonical setup recipe and walk you through install, pairing, and troubleshooting:

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://&lt;host&gt;: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.

Already installed? The same recipe is auto-loaded as a Hermes skill — invoke `/hermes-relay-self-setup` from any chat for re-setup or "is everything wired correctly?" checks.

Development

# Android: open the repo root in Android Studio, wait for Gradle sync, Run (Shift+F10).
scripts/dev.bat build      # Build sideload debug APK
scripts/dev.bat compile    # Compile sideload Kotlin only
scripts/dev.bat test-one &quot;com.hermesandroid.relay.SomeTest&quot;  # Focused unit test
scripts/dev.bat install-fast  # arm64 phone build + install + launch
scripts/dev.bat release    # Build signed release APK
scripts/dev.bat bundle     # Build release AAB for Google Play
scripts/dev.bat run        # Build sideload + install + launch + logcat
scripts/dev.bat test       # Run sideload debug unit tests
scripts/dev.bat version    # Show current version
scripts/dev.bat relay      # Start the relay server (dev, no TLS)

Tech Stack

Component	Stack
Android app	Kotlin 2.4, Jetpack Compose, Material 3, OkHttp
Hermes-Relay CLI	TypeScript, Bun-compiled native binary, Node ≥21 (source/dev), zero runtime deps
Server / plugin	Python 3.11+, aiohttp
Serialization	kotlinx.serialization (Android)
Build	AGP 9.3.1, Gradle 9.6.1, JVM toolchain 17 (Android); `tsc` + `bun build --compile` (CLI)
CI/CD	GitHub Actions — lint, build, test, APK artifact, CLI binaries per platform
Min SDK	26 (Android 8.0) · Target SDK 36

Repository structure

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

Running the server / plugin from a clone
End users should install via the [one-liner](#4--optional-install-relay-for-power-tools) above. For local development:

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/ &amp;&amp; docker run -d --network host --name hermes-relay hermes-relay

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

Then restart hermes and run `hermes pair` to verify. The 35 `android_*` and 25 `desktop_*` tools register regardless of hermes-agent version. See [docs/relay-server.md](docs/relay-server.md) for TLS, systemd, and full setup.

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

Built with the help of Humans and AI Agents

hermes-relay