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.

Documentation · Releases · Changelog · Hermes Agent

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.

Install → connect → talk, in about two minutes.

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

The app needs your Hermes API server enabled and reachable from your phone, plus an API key — the token the app sends to authenticate Chat (pick any value you like). Installing Hermes and choosing a provider is standard Hermes setup; the full walkthrough covers Windows, the dashboard for Manage, LAN scan, and QR setup.

hermes setup --portal                      # install / log in / pick a provider — skip if already done

mkdir -p ~/.hermes
API_SERVER_KEY="$(openssl rand -hex 32)"   # strong random key — or substitute your own memorable value
cat >> ~/.hermes/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_HOST=0.0.0.0
API_SERVER_PORT=8642
API_SERVER_KEY=$API_SERVER_KEY
EOF
chmod 600 ~/.hermes/.env

echo "Android API URL: http://<this-computer-ip>:8642   key: $API_SERVER_KEY"
hermes gateway

API_SERVER_ENABLED turns the API server on; API_SERVER_HOST=0.0.0.0 makes it reachable on your LAN (the default is localhost-only); API_SERVER_KEY is the bearer token the app sends — your choice of value.

Heads up on 0.0.0.0: that exposes the API to every device on your network — fine on a trusted home LAN, but off it keep the key set and front it with Tailscale or an HTTPS reverse proxy (Remote access) rather than exposing it directly. You don't have to type the key on your phone — Scan for Hermes on LAN, or have your agent make a setup QR (below). For Manage (skills, models, keys), also run the Hermes dashboard — see Getting Started.

Open the app and pick how to connect — any of:

• Standard Hermes → tap Scan for Hermes on LAN to auto-find the server, then enter your key.
• Standard Hermes → type the address (http://<host>:8642) and key by hand.
• Scan setup QR → ask your Hermes agent to generate a QR with your URL + key (e.g. {"api_url":"http://<host>:8642","api_key":"<key>"}) and scan it.

The wizard probes everything and finishes with a capability card:

If your dashboard requires sign-in, do it once under the Manage tab — the same session unlocks voice. That's the whole standard setup.

Going places? Put your server's Tailscale URL in the setup form's Remote access field (or add a route any time under Settings → Connections → Routes). The app uses LAN at home and switches routes automatically when you leave. See Remote access.

Install the Relay plugin on the server only when you want Terminal, Bridge phone control, relay sessions, media routes, or the realtime voice engine:

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

The installer clones to ~/.hermes/hermes-relay/, registers the plugin/skill paths, and can install a systemd user service. 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.

• Update: hermes-relay-update (idempotent) — or re-run the install one-liner.
• Uninstall: bash ~/.hermes/hermes-relay/uninstall.sh — reverses every step, 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) · hermes-agent v0.8.0+ with Python 3.11+ on the server.

Cold start	Streaming chat	Hands-free voice	Session history
Command palette	Manage your agent	Connections & routes	Settings

_{▶ Watch the demo on the docs site}

• Streaming chat — direct SSE to the Hermes API server 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.

Alpha · Windows today (macOS / Linux coming soon). A single self-contained binary — no Node required. Binaries 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                            # headless 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 a separate desktop-v* release track.

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

Phone        (HTTP/SSE) --> Hermes API Server (:8642)   [chat — direct]
Phone        (HTTP)     --> Hermes Dashboard  (:9119)   [manage + standard voice — cookie sign-in]
Phone        (WSS/HTTP) --> Relay             (:8767)   [terminal, bridge, media, relay voice, sessions]
CLI          (WSS)      --> Relay             (:8767)   [machine tools, tui, terminal]

Chat connects directly to the Hermes API server with the API key — the same pattern Open WebUI and other Hermes frontends use. Manage and standard 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 (preferred automatically when paired). One QR can configure API, dashboard, and relay routes without merging their auth models.

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

# 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)

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-server / 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

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.

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.

MIT — Copyright (c) 2026 Axiom-Labs

Built with the help of Humans and AI Agents