Hermes Android Native Remote Client

A production-grade, native Android client application for Hermes, implementing Protocol & Architecture Contract v1 with Multi-Hermes Connection Manager and Unified Sessions.

Built with Kotlin, Jetpack Compose (Material 3), Coroutines, Room Database, OkHttp, and Android Keystore (EncryptedSharedPreferences).

---

🌟 Architecture Overview

   ┌─────────────────────────────────────────────────────────────────────────┐
   │                          Hermes Android Client                          │
   │  ┌───────────────────────────────────────────────────────────────────┐  │
   │  │                      Jetpack Compose UI (M3)                      │  │
   │  │   • Multi-Host Switcher • Unified Sessions • Attributed Chat      │  │
   │  └─────────────────────────────────┬─────────────────────────────────┘  │
   │                                    │ StateFlow / Actions                │
   │  ┌─────────────────────────────────▼─────────────────────────────────┐  │
   │  │                   Unified Session Repository                      │  │
   │  │   • Logical Unified Sessions   • Context Synchronization Delta    │  │
   │  │   • Host-Tagged Event Routing  • Local Persistence (Room DB)      │  │
   │  └──────────────────┬──────────────────────────────┬─────────────────┘  │
   │                     │                              │                    │
   │  ┌──────────────────▼──────────────────┐  ┌────────▼─────────────────┐  │
   │  │      Hermes Connection Manager      │  │   Encrypted Token Vault  │  │
   │  │   • Map<HostId, HostRuntime>        │  │   (Host-Scoped Keystore) │  │
   │  └───────┬─────────────────────────┬───┘  └──────────────────────────┘  │
   │          │                         │                                    │
   │  ┌───────▼─────────────┐   ┌───────▼─────────────┐                      │
   │  │   Host #1 Runtime   │   │   Host #2 Runtime   │                      │
   │  │  (OkHttp WS + REST) │   │  (OkHttp WS + REST) │                      │
   │  └───────┬─────────────┘   └───────┬─────────────┘                      │
   └──────────┼─────────────────────────┼────────────────────────────────────┘
              │                         │
              ▼                         ▼
   ┌──────────────────────┐  ┌──────────────────────┐
   │    Hermes Host #1    │  │    Hermes Host #2    │
   │   (Windows Office)   │  │    (Linux Server)    │
   │   `hermes serve`     │  │   `hermes serve`     │
   └──────────────────────┘  └──────────────────────┘

---

🚀 Key Multi-Host Features

1. Multi-Hermes Connection Manager:

   • Save and manage multiple independent Hermes installations (e.g. Workstation, Linux Server, Cloud VM).
   • Independent WebSocket connections, concurrent state management, and isolated reconnect loops.
   • Individual host health badges: Online, Connecting, Offline, Auth Expired.

2. Unified Sessions & Context Synchronization:

   • Create one logical conversation (UnifiedSession) that spans multiple physical Hermes hosts.
   • Seamlessly switch active execution hosts mid-conversation via the top-bar dropdown.
   • Delta Context Sync: When switching execution to a new host, Hermes automatically transfers a bounded context window of the last 10 messages (or since the last synced point, up to 10 max). This context is transferred securely as a distinct system preamble, completely separately from the user's prompt text, avoiding stealth concatenation. Sensitive variables, tokens, API keys, and credentials are automatically stripped/redacted from the transferred context payload before sending.
   • Host Attribution: Every response bubble, tool card, and thinking trace displays its originating host badge (e.g. [Office PC], [Linux Server]).
   • Non-Blocking Host Switching: If Host #1 is executing a long tool or computation and you switch to Host #2, Host #1 completes its work in the background and commits results into the shared timeline.

3. Isolated Host Security & Approvals:

   • Host-scoped credentials stored securely in Android Keystore (hostId -> tokens).
   • Host-Targeted Approvals & Clarifications: Dangerous command approvals (approval.request) and sudo prompts route back strictly to the exact host runtime and native session that emitted them.

4. Background Execution & Synchronization:

   • Long-running host tasks (like heavy computations, builds, or lengthy agent turns) will continue safely in the background even if you minimize the application or switch apps.
   • When active tasks are running, a foreground service (notification: "Hermes Agent active") keeps the sync socket alive and commits incoming tool usage or results back to the local database timeline.
   • The service terminates automatically the moment the task completes or errors out, preserving battery life and conforming to Android Play Store dataSync foreground policies.

5. Local Persistence (Room DB):

   • Full offline caching for UnifiedSession, HostSessionBinding, and UnifiedMessage.
   • Raw native session browser for inspecting individual host histories.

---

🖥️ Hermes Host Setup

Windows Host

hermes serve --host 0.0.0.0 --port 9119

With OAuth / GitHub Auth:

$env:HERMES_AUTH_REQUIRED="true"
$env:HERMES_AUTH_PROVIDERS="github"
$env:HERMES_AUTH_GITHUB_CLIENT_ID="<your_client_id>"
$env:HERMES_AUTH_GITHUB_CLIENT_SECRET="<your_client_secret>"
hermes serve --host 0.0.0.0 --port 9119

Linux Host

export HERMES_AUTH_REQUIRED="true"
export HERMES_AUTH_PROVIDERS="github"
export HERMES_AUTH_GITHUB_CLIENT_ID="<your_client_id>"
export HERMES_AUTH_GITHUB_CLIENT_SECRET="<your_client_secret>"

hermes serve --host 0.0.0.0 --port 9119

---

🧪 Testing & Verification

Run the full automated test suite:

.\gradlew.bat test

Run Android Lint:

.\gradlew.bat lint

Assemble Debug APK:

.\gradlew.bat assembleDebug

---

📱 Instant QR Onboarding — Hermes Pair (hermes-pair/)

Inside the hermes-pair/ directory is the cross-platform desktop companion application written in Rust. It runs on Windows and Linux to auto-discover your local IP and generate a secure QR code for instant onboarding with Hermes Android.

1. Download Prebuilt Binaries (GitHub Releases)

Download prebuilt binaries and SHA256SUMS.txt from the latest GitHub Releases.

Verifying SHA-256 Checksums:

• Windows (PowerShell):

  Get-FileHash .\hermes-pair-windows-x86_64.exe -Algorithm SHA256
  # Compare the resulting hash with SHA256SUMS.txt

• Linux:

  sha256sum -c SHA256SUMS.txt
  # or verify directly:
  sha256sum hermes-pair-linux-x86_64

2. Running Hermes Pair

Windows (GUI or CLI):

# Launch GUI window (defaults to HTTPS pairing with TLS pinning)
.\hermes-pair-windows-x86_64.exe

# Terminal QR output with pinned certificate fingerprint
.\hermes-pair-windows-x86_64.exe qr --port 9119 --fingerprint "AA:BB:CC:DD:..."

Linux (GUI or Headless Server):

chmod +x hermes-pair-linux-x86_64

# Launch GUI window
./hermes-pair-linux-x86_64

# Headless / Terminal QR with pinned certificate fingerprint
./hermes-pair-linux-x86_64 --terminal --port 9119 --fingerprint "AA:BB:CC:DD:..."

3. Security Architecture: TLS Pinning & Strict Network Policy

• Strict Network Policy: Android's network_security_config.xml enforces cleartextTrafficPermitted="false" across base configurations, preventing unencrypted transport of authentication tokens or user prompts.
• TLS Fingerprint Trust (TlsFingerprintTrust): During QR onboarding via Pairing Protocol v2, the host passes its SHA-256 TLS certificate fingerprint. Hermes Android securely validates self-signed or enterprise TLS certificates without requiring device-wide root certificate installation or cleartext exceptions.

4. Building Hermes Pair from Source:

cd hermes-pair
cargo test
cargo build --release

The compiled binaries will be located at:

• Windows: hermes-pair/target/release/hermes-pair.exe
• Linux: hermes-pair/target/release/hermes-pair