ochenstarik/hermes-android
1
0
Fork 0
Code Issues Pull requests 15 Projects Releases Packages Wiki Activity Actions
hermes-android/README.md

187 lines
9.9 KiB
Markdown
Raw Permalink Blame History

# 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
```powershell
hermes serve --host 0.0.0.0 --port 9119
```
With OAuth / GitHub Auth:
```powershell
$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
```bash
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:
```powershell
.\gradlew.bat test
```
Run Android Lint:
```powershell
.\gradlew.bat lint
```
Assemble Debug APK:
```powershell
.\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](https://github.com/ochenstarik-ui/hermes-android/releases).
#### Verifying SHA-256 Checksums:
- **Windows (PowerShell)**:
```powershell
Get-FileHash .\hermes-pair-windows-x86_64.exe -Algorithm SHA256
# Compare the resulting hash with SHA256SUMS.txt
```
- **Linux**:
```bash
sha256sum -c SHA256SUMS.txt
# or verify directly:
sha256sum hermes-pair-linux-x86_64
```
### 2. Running Hermes Pair
#### Windows (GUI or CLI):
```powershell
# 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):
```bash
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](docs/pairing-protocol-v2.md), 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:
```bash
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`
Reference in a new issue View git blame Copy permalink