122 lines
5.7 KiB
Markdown
122 lines
5.7 KiB
Markdown
# Hermes Android Native Remote Client
|
|
|
|
A production-grade, native Android client application for **Hermes**, implementing Protocol & Architecture Contract v1.
|
|
|
|
Built with **Kotlin**, **Jetpack Compose (Material 3)**, **Coroutines**, **OkHttp**, and **Android Keystore (EncryptedSharedPreferences)**.
|
|
|
|
---
|
|
|
|
## 🌟 Architecture Overview
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Hermes Android Client │
|
|
│ ┌───────────────────────────────────────────────────┐ │
|
|
│ │ Jetpack Compose UI (M3) │ │
|
|
│ │ • Connections • Sessions • Chat & Approvals │ │
|
|
│ └─────────────────────────┬─────────────────────────┘ │
|
|
│ │ StateFlow / Actions │
|
|
│ ┌─────────────────────────▼─────────────────────────┐ │
|
|
│ │ Hermes Gateway Layer │ │
|
|
│ │ • Reconnection Loop with Exponential Backoff │ │
|
|
│ │ • Session State Reconciliation │ │
|
|
│ │ • Event Stream Dispatcher │ │
|
|
│ └──────────┬──────────────────────────┬─────────────┘ │
|
|
│ │ JSON-RPC / Ticket │ PKCE Auth │
|
|
│ ┌──────────▼──────────┐ ┌──────────▼──────────────┐ │
|
|
│ │ OkHttp WebSocket │ │ Loopback Auth Server │ │
|
|
│ │ (Single-Use Auth) │ │ (127.0.0.1:<port>) │ │
|
|
│ └──────────┬──────────┘ └──────────┬──────────────┘ │
|
|
└─────────────┼──────────────────────────┼─────────────────┘
|
|
│ │
|
|
▼ ▼
|
|
┌─────────────────────────────────────────────────────────┐
|
|
│ Hermes Host │
|
|
│ (`hermes serve`) │
|
|
│ │
|
|
│ • `GET /api/status` • `GET /auth/native/...`│
|
|
│ • `POST /api/auth/ws-ticket` • `WS /ws?ticket=...` │
|
|
└─────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
---
|
|
|
|
## 🚀 Getting Started & Host Setup
|
|
|
|
### 1. Windows Host Setup
|
|
|
|
Run the Hermes server binding to all interfaces (or your LAN / Tailscale IP):
|
|
|
|
```powershell
|
|
hermes serve --host 0.0.0.0 --port 9119
|
|
```
|
|
|
|
To configure GitHub authentication:
|
|
```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
|
|
```
|
|
|
|
### 2. Linux Host Setup
|
|
|
|
```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
|
|
```
|
|
|
|
---
|
|
|
|
## 📱 Android Client Features
|
|
|
|
1. **Host Connection Manager**:
|
|
- Save multiple Hermes host endpoints.
|
|
- Live endpoint verification (`GET /api/status`).
|
|
- Cleartext HTTP toggling with explicit security warning badges for local development.
|
|
|
|
2. **Native PKCE Authentication**:
|
|
- RFC 7636 & RFC 8252 compliant PKCE loopback authentication on `127.0.0.1:<ephemeral_port>`.
|
|
- Single-use WebSocket tickets with 30s TTL.
|
|
- Credentials securely stored via Android Keystore & `EncryptedSharedPreferences`. Zero token logging.
|
|
|
|
3. **Session Management**:
|
|
- Resume durable sessions (`DurableSessionId`) or create new sessions.
|
|
- Dynamic reconciliation across network disconnects.
|
|
|
|
4. **Real-time Chat Experience**:
|
|
- Streaming token deltas (`message.delta`).
|
|
- Collapsible reasoning & chain-of-thought section (`thinking.delta`).
|
|
- Real-time tool execution tracking cards (`tool.start`, `tool.progress`, `tool.complete`).
|
|
- **Interactive Approvals**: Immediate in-stream approval card for dangerous commands (`Allow Once`, `Allow Always`, `Deny`).
|
|
- **Clarifications & Sudo**: Masked dialogs for `sudo.request`, `secret.request`, and `clarify.request`.
|
|
- Interrupt / Stop execution control.
|
|
|
|
---
|
|
|
|
## 🔒 Security Best Practices for Remote Access
|
|
|
|
- **Do NOT expose cleartext HTTP directly to the public internet.**
|
|
- **Recommended**: Connect via **Tailscale**, **WireGuard**, or a TLS Reverse Proxy (Caddy / Nginx) with HTTPS & WSS.
|
|
- The Android client strictly enforces `usesCleartextTraffic="false"` at the manifest level by default.
|
|
|
|
---
|
|
|
|
## 🧪 Testing & Verification
|
|
|
|
Run all unit tests via Gradle:
|
|
|
|
```powershell
|
|
.\gradlew testDebugUnitTest
|
|
```
|
|
|
|
Build the release or debug APK:
|
|
|
|
```powershell
|
|
.\gradlew assembleDebug
|
|
```
|