Hermes-Relay: Android App and CLI for Hermes Agent

Configuration Reference

The sources do not document individual configuration options beyond the commands and flags shown in the Setup section. The following table summarizes the key commands and their purposes:

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.

The Android app uses Kotlin 2.0, Jetpack Compose, Material 3, and OkHttp. The Hermes-Relay CLI is written in TypeScript and compiled to a native binary with Bun, requiring Node >=21 for source development but zero runtime dependencies. The server/plugin is written in Python 3.11+ using aiohttp. Serialization on Android uses kotlinx.serialization. Build tools are AGP 9, Gradle 8.13, JVM toolchain 17 for Android, and tsc + bun build --compile for the CLI. CI/CD is handled by GitHub Actions with separate pipelines for Android, plugin, and desktop builds. The minimum SDK is 26 (Android 8.0) with a target SDK of 35.

Requirements and Limitations

• Android: Android 8.0+ (SDK 26) is required.
• Server: A current upstream hermes-agent with the Dashboard/Gateway enabled is required. Python 3.11+ is needed on the server for the Relay plugin.
• API server and Relay are optional. A vanilla hermes-agent install is enough for chat, management, and voice. The Relay plugin is only needed for terminal, phone control, or CLI tools.
• CLI is alpha. Self-contained binaries ship for Windows x64, Linux x64, and macOS x64/arm64. Assets are unsigned during the experimental phase, so SmartScreen / Gatekeeper warnings are expected.
• Sideload builds add direct SMS, contact search, one-tap dialing, and location awareness, but these features are not available in the Google Play version.
• Phone control (bridge) is guarded by a per-app blocklist (banking/2FA blocked by default), destructive-verb confirmation, idle auto-disable, and a full activity log.
• The legacy installer is an alternative to the plugin-manager install and provides systemd user service, shell shims, and the full clone/update workflow. It is not required for most users.
• The compatibility hook (hermes relay compat) is only needed for older Hermes builds that do not support the plugin manager.

Troubleshooting

The sources do not document specific failure modes or troubleshooting steps beyond the verification commands. The following verification steps are provided:

• Server verification: Run hermes-status on the server to check the relay status.
• CLI verification: Run hermes-relay doctor to check the CLI installation and pairing status.
• AI-agent setup recipe: If an AI assistant manages your server, paste the following block into its chat to fetch the canonical setup recipe and walk 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://<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.

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.

If the Android app cannot connect, ensure the Hermes Dashboard is running and reachable from the phone over a trusted LAN, Tailscale, or HTTPS reverse proxy. The app probes available upstream capabilities and shows a connection summary. If the relay is not paired, the app will show "Relay: Optional extensions, fine to leave unpaired" in the capability card.

For CLI issues, ensure the relay server is running (hermes relay start --no-ssl or with TLS) and that the CLI is paired with the correct remote address (hermes-relay pair --remote ws://<host>:8767). The CLI must be running as a daemon (hermes-relay daemon start) for the agent to reach the machine.

If the legacy installer fails, check that the one-liner URL is correct and that the system has curl and bash available. The uninstall script is at ~/.hermes/hermes-relay/uninstall.sh and supports --dry-run, --keep-clone, and --remove-secret flags.

For development, the relay server can be started from a clone with python -m plugin.relay --no-ssl or via 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 by symlinking:

ln -s "$PWD/plugin" ~/.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.

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)

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

License

MIT, Copyright (c) 2026 Axiom-Labs. Built with the help of Humans and AI Agents.