Hermes-Relay Reference

Hermes-Relay is a companion for the Hermes agent platform. It consists of a native Android app for streaming chat, voice, and agent management, and a single-binary CLI that gives the agent access to files, terminal, search, and screenshots on paired machines. This document covers every capability, procedure, parameter, constraint, and failure mode.

When to Use Hermes-Relay

Use Hermes-Relay in these situations:

• You want to interact with your Hermes agent from an Android phone via chat, voice, or management.
• You need the agent to control your phone screen (sideload builds only) or access phone features like SMS, contacts, dialing, and location.
• You want the agent to have hands-on access to a computer's files, terminal, search, screenshots, clipboard, and editor via the CLI.
• You need to pair multiple Hermes servers (home, work, dev, prod) and switch between them.
• You want to use the agent away from home with automatic route switching (LAN at home, fallback elsewhere).
• You need notification triage, summarization, and routing by the agent.

Prerequisites

Before you begin, ensure these are in place:

• Hermes Agent must be installed and running with Dashboard/Gateway enabled.
• Android 8.0+ (SDK 26) device for the Android app.
• Python 3.11+ on the server for the Relay plugin.
• Node 21 or later for CLI source or development (the compiled binary has no runtime dependencies).
• For remote access: Tailscale or HTTPS reverse proxy setup.
• For phone control (bridge): Relay plugin installed and paired, sideload build of Android app.

Capabilities

Android App

The native Android app provides streaming chat via WebSocket through the dashboard, with SSE fallback through the API server. It supports live markdown rendering, tool-call cards, session history, a searchable command palette, file attachments, quote-in-reply, conversation share, and send-while-streaming queuing.

From the app you can perform full Hermes dashboard management: switch models, manage API keys (write-only, masked, rate-limited reveal), create and edit profiles including SOUL.md, and browse, install, and update skills.

Hands-free voice works on a vanilla install (speech via the server's providers, unlocked by Manage sign-in). Relay-paired setups add per-profile voice and opt-in provider-native Realtime Agent with background task handoff.

The app supports multi-connection with profiles. You can pair multiple servers, switch in one tap, and overlay a profile's model and SOUL.md per chat.

Phone control (bridge) via Relay lets the agent read the screen and perform tap, type, swipe, scroll, screenshots, clipboard, media keys, and batched macros. This is guarded by a per-app blocklist (banking and 2FA apps blocked by default), destructive-verb confirmation, idle auto-disable, and a full activity log.

The notification companion provides opt-in access for the agent to triage, summarize, and route incoming notifications.

Security features include QR pairing, Android Keystore session storage (StrongBox-preferred), TOFU cert pinning, per-channel time-bound grants, and user-chosen session TTL.

Local-only analytics (Stats for Nerds) show TTFT, token usage, stream health, and peak-time charts.

Sideload builds add direct SMS, contact search, one-tap dialing, and location awareness.

Hermes-Relay CLI (Alpha)

The CLI is a single binary for Windows x64, Linux x64, and macOS x64/arm64. It provides these tools: read_file, write_file, terminal, search_files, screenshot, clipboard, open_in_editor, and more. It has a one-time consent gate and interactive diff approval for patches. The --no-tools flag acts as a kill-switch.

The CLI pairs against the same relay and credential store as the Android app. Pair once from either, and both work.

Windows has an optional systray (right-click only, no dashboard or app window) with TUI launch, daemon controls, pairing, grant review, audit, diagnostics, logs, desktop-use status and cancellation, sign-in startup, and emergency stop.

Dashboard Plugin

The dashboard plugin adds a Relay tab showing paired devices, bridge activity, and media tokens in the web UI.

Multi-Language Support

The app supports Deutsch, Espanol, Japanese, Portuguese (Brasil), and Simplified Chinese (AI-assisted catalogs).

Automatic Route Switching

The app provides automatic route switching for remote access. It uses LAN at home and falls back elsewhere. An unreachable server gets a diagnosis, not just a red dot.

Self-Updating

The Hermes-Relay CLI self-updates via GitHub Releases.

Plugin-Manager Install

The plugin-manager install owns the plugin code, dashboard tab, CLI commands, and agent tools. The legacy installer adds a systemd user service, shell shims, and a clone/update workflow.

Procedures

Android Quick Start

1. Install the app. Either get it from Google Play (easiest, auto-updates) or download the -sideload-release.apk from the newest android-v* release on GitHub Releases and open it (allow browser to install unknown apps).
2. Ensure Hermes Dashboard is running on your server. Run hermes setup --portal (if not already done) then hermes dashboard.
3. Make the dashboard reachable from your phone over a trusted LAN, Tailscale, or HTTPS reverse proxy.
4. Open the app, choose "Connect to Hermes", enter or discover the dashboard address (conventionally http://<host>:9119). Sign in through the dashboard's configured provider when prompted. The app probes capabilities and shows a connection summary.
5. (Optional) Add the Dashboard's Tailscale address under Settings, Connections, Routes for remote access. No API server or API key required.
6. (Optional) Install the Relay plugin on the server for power tools. Run hermes plugins install Codename-11/hermes-relay/plugin --enable, then hermes relay doctor, hermes relay start --no-ssl, hermes pair. 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.

CLI Installation and Pairing (Windows)

1. Run the install script:

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

2. Pair with the relay: hermes-relay pair --remote ws://<host>:8767 (once).
3. Start the daemon: hermes-relay daemon start (background tool router).
4. Update: hermes-relay update (self-update via GitHub Releases).

Plugin-Manager Uninstall

1. If the optional compatibility hook was installed, run hermes relay compat remove --all.
2. Run hermes plugins remove hermes-relay.

Legacy Installer Uninstall

1. Run bash ~/.hermes/hermes-relay/uninstall.sh. This 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.

Running Server/Plugin from Clone (Development)

• If plugin installed: hermes relay start --no-ssl.
• Or from repo checkout: python -m plugin.relay --no-ssl.
• Or Docker: docker build -t hermes-relay relay_server/ && docker run -d --network host --name hermes-relay hermes-relay.
• Or live-edit: ln -s "$PWD/plugin" ~/.hermes/plugins/hermes-relay, then restart hermes and run hermes pair to verify.

AI Agent Setup Prompt

Paste the provided block into an AI assistant's chat. It will fetch the canonical setup recipe and guide through: verifying hermes-agent is installed, running the server-plugin install one-liner, connecting phone by Vanilla Hermes API URL/key first then optionally pairing Relay, or pairing laptop via CLI, and verifying with hermes-status (server) or hermes-relay doctor (CLI).

Server Plugin Install via One-Liner

Run the following command to install the server plugin directly:

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

After installation, pair the relay with:

hermes pair

CLI Pairing from Server

From the server, you can also initiate CLI pairing using the command:

/hermes-relay-pair

On Windows, after pairing, verify the connection with:

hermes-status

And from the CLI, run:

hermes-relay doctor

Android App Pairing with Manual Code

If QR scanning is not possible, use a manual pairing code. On the Android app, go to Settings, Connections, Advanced to view the manual code (e.g., ABCD12). On the server, run:

hermes pair --register-code ABCD12

Replace ABCD12 with the actual code shown on the phone.

CLI Pairing from Server with Remote Address

When pairing the CLI from the server to a remote relay, use the --remote flag:

hermes-relay pair --remote ws://<host>:8767

This is a one-time operation; subsequent daemon starts use the stored credentials.

Daemon Control on Windows

After pairing, manage the daemon with these commands:

• Start: hermes-relay daemon start
• Stop: hermes-relay daemon stop
• Status: hermes-relay daemon status

The Windows systray provides right-click access to these controls plus pairing, grant review, audit, diagnostics, logs, desktop-use status and cancellation, sign-in startup, and emergency stop.

Compatibility Hook Management

The plugin-manager install includes an optional legacy API compatibility hook. Manage it with:

hermes relay compat status
hermes relay compat install
hermes relay compat remove

Use hermes relay compat remove --all before uninstalling if the hook was installed.