Hermes-Android

Hermes-Android brings the Hermes WebUI experience to Android without turning it into a second product.

It keeps Hermes WebUI as the real application surface and adds the Android capabilities that matter on a phone or tablet: a hardened WebView, trusted navigation, native sharing, uploads and downloads, notifications, secure local settings, update delivery, and recovery paths when the mobile runtime gets in the way.

If Hermes WebUI is the product, Hermes-Android is the native shell that makes it feel at home on Android.

• Your Hermes workspace, on Android
• Native where Android matters
• WebUI where Hermes matters

See It

Hermes-Android keeps the real Hermes experience intact, then makes it feel right on Android.

Requires a running Hermes WebUI instance. On first launch, enter the URL for your Hermes server.

Why This Exists

Hermes already has a strong web experience. Android should not fork that experience or reimplement it badly.

This repository exists to solve the Android-specific problems well:

• Host Hermes WebUI inside a secure, reliable Android shell
• Preserve WebUI behavior instead of replacing it with app-specific workflows
• Fix Android WebView compatibility issues that break real usage
• Add Android-native capabilities where the browser alone is not enough
• Keep distribution, signing, updates, and device behavior production-ready

The result is a native-feeling Android client that still behaves like Hermes WebUI, not a parallel mobile rewrite that drifts out of sync.

Who This Is For

Hermes-Android is built for:

• Hermes users who want their real workspace on Android, not a reduced mobile fallback
• Self-hosters who need HTTP or HTTPS support for trusted local or remote Hermes deployments
• Testers and contributors who want a proper Android distribution channel instead of a one-off wrapper
• Teams that want Hermes WebUI parity while still respecting Android platform expectations

Why Not Just Use Chrome?

Because opening Hermes in a mobile browser is not the same as integrating it properly with Android.

Hermes-Android adds the platform work that a plain browser tab does not own:

• Trusted in-app navigation and host-boundary enforcement
• Native share-sheet intake, uploads, downloads, and camera capture
• Android-backed notifications and update delivery
• Recovery flows for bad server settings, broken WebView states, and reconnect windows
• WebView-specific compatibility fixes so Hermes surfaces render and behave correctly on Android

The goal is not to replace the web app. The goal is to make the web app feel first-class on Android.

What Hermes-Android Owns

• Secure WebView hosting for trusted Hermes HTTP and HTTPS deployments
• Host allowlist enforcement and external handoff for untrusted links
• Android lifecycle, recovery, deep links, and session restore behavior
• Native settings, encrypted local storage, and server profile management
• Share-sheet intake, file uploads, downloads, and camera capture
• Android-backed Hermes notifications and update alerts
• Release packaging for both Play and GitHub channels

What Stays In Hermes WebUI

• Product behavior and feature workflows
• Chat, sessions, workspace, routing, and API behavior
• UI layout, styling, animations, and dashboard behavior
• Cross-platform features that should work the same in browser, desktop, and Android

If a change belongs to Hermes everywhere, it belongs in WebUI first.

Highlights

Native Hermes, not a compromised wrapper

• Kotlin + Jetpack Compose app shell around Hermes WebUI
• Hardened WebView defaults with DOM storage and browser-managed HTTP and service-worker cache behavior
• Pull-to-refresh, loading, offline, and recovery flows designed for Android
• Deep link support for Hermes sessions through hermes://session/{id}
• Native recovery route through hermes://app/settings

Android-specific compatibility work that matters

• Measured layout/visual-viewport repair for Android WebView builds that collapse Hermes layout, including shifting prompt surfaces fully above the software keyboard
• Clarify-specific initial-autofocus handling that keeps multiple-choice options visible without blocking editable WebUI dialogs or later validation focus
• System-bar safe inset handling so Hermes content does not sit under Android status and navigation bars
• Forced WebView darkening disabled so Hermes controls its own visual presentation
• Local network permission handling for Android 16+ so LAN-hosted Hermes WebUI instances can load inside the WebView
• Microphone compatibility handling so trusted Hermes pages can use Android-supported capture paths
• OAuth/OIDC callback handling that keeps trusted sign-in flows in-app until the declared Hermes callback returns

Real Android integration

• File uploads and downloads, including direct camera capture when pages request image capture
• Share-to-app intake for text and files
• Android-backed browser notifications for Hermes WebUI alerts
• Optional ongoing background activity notification for trusted Hermes sessions
• Persistent authenticated session-stream monitoring (/api/session/stream) for background activity updates, with reconnect polling fallback when live streaming is unavailable
• Optional debug-log capture with persistent foreground notification and one-tap stop action
• Channel-aware app updates: Play uses in-app update flow, GitHub APK builds download and hand off to installer in-app
• GitHub APK updates surface a stateful in-app action flow (Check -> Download -> Install) and still show an install-ready notification when Hermes is backgrounded

Security and trust boundaries

• Only http:// and https:// Hermes hosts are supported in-app
• Allowlisted Hermes navigation stays in-app; other web links are externalized
• Non-web schemes are blocked
• Notification routing, microphone access, and callback handling stay scoped to trusted Hermes origins
• Local settings are encrypted with Android Keystore-backed storage
• Optional VPN/Tailscale startup guard for Tailscale-addressed Hermes servers (*.ts.net, Tailscale CGNAT/ULA ranges)
• Optional VPN launch-app picker with search plus a Tailscale default package fallback before Android VPN settings when the VPN/Tailscale guard blocks a server load; Hermes first asks Tailscale to connect while keeping Hermes on screen, keeps an every-second /api/status probe alive, automatically reloads once VPN and server are ready, and only opens Tailscale if auto-connect has not established a tunnel within ten seconds

What It Feels Like

When Hermes-Android is doing its job well, the experience should be simple:

• Open the app and land in your actual Hermes environment
• Stay inside Hermes for trusted work instead of bouncing between browser surfaces
• Use Android-native sharing, capture, notifications, and recovery where the phone should help
• Keep Hermes WebUI as the source of truth for product behavior and interface flow

Availability

Hermes-Android currently publishes through two release channels:

• Google Play production via the official release build
• GitHub APK distribution via the side-by-side github build

Current checked-in release metadata:

• Version name: 1.1.0
• Version code: 10100
• Play application ID: com.hermeswebui.android
• GitHub application ID: com.hermeswebui.android.github
• Compile SDK / target SDK: 37

If you want access to the Play release, install from Google Play or sideload the GitHub APK from the Releases page.

Quick Start

git clone https://github.com/hermes-webui/hermes-android.git
cd hermes-android
.\gradlew.bat assembleDebug --no-daemon

Open the repository in Android Studio to run on an emulator or device.

Requirements:

• Android Studio with Android SDK 37
• JDK 17 or newer compatible with Gradle
• A reachable Hermes WebUI URL over HTTP or HTTPS

Configuration

Default app strings live in:

• app/src/main/res/values/strings.xml

Important values:

• default_server_url - default Hermes WebUI URL
• default_dashboard_url - optional explicitly configured dashboard origin used only for Android-side Custom Tab matching
• app_name - Android launcher label

Android identity and app-level wiring live in:

• app/build.gradle.kts
• app/src/main/AndroidManifest.xml
• settings.gradle.kts

The shipped WebUI default is a placeholder HTTPS origin and the shipped dashboard default is blank. In normal use, WebUI owns dashboard auto-detect and persistence.

Build, Signing, and Release

Local signed release builds use an untracked repo-root keystore.properties file. CI builds use the corresponding ANDROID_KEYSTORE_* environment variables and secrets.

Local signing setup:

1. Copy keystore.properties.example to keystore.properties.
2. Fill in the real keystore path and passwords.
3. Keep that file untracked.

Example:

storeFile=C:/path/to/upload-keystore.jks
storePassword=replace-me
keyAlias=upload
keyPassword=replace-me

Useful commands:

.\gradlew.bat test --no-daemon
.\gradlew.bat lintDebug --no-daemon
.\gradlew.bat assembleDebug --no-daemon
.\gradlew.bat stageGithubReleaseApk --no-daemon
.\gradlew.bat printReleaseVersionName --no-daemon

Device check:

.\gradlew.bat connectedDebugAndroidTest --no-daemon

Repository tooling checks can be run with:

python -m unittest discover -s tools/tests -p 'test_*.py' -v
python tools/check_markdown.py

The docs-only CI short-circuit is fail-safe: only a non-empty diff containing Markdown files exclusively can skip the Android Gradle gates. Unreadable, empty, invalid, renamed, or mixed diffs run the full suite.

Release automation is centered on:

• .github/workflows/1-orchestration-release.yml
• .github/workflows/2-publish-github-apk.yml

Optional/manual Play workflows:

• .github/workflows/3-publish-play-store-production.yml
• .github/workflows/play-store-beta-manual.yml

That flow builds:

• hermes-webui-v<version>-github.apk for GitHub/device installs
• hermes-webui-v<version>.aab for Google Play production

Release orchestration builds the reviewed appVersionName already checked into Git and never commits or pushes source changes. versionCode is derived from semantic version as major*10000 + minor*100 + patch; update the Gradle and README metadata together before starting a release.

See RELEASE.md for the operator workflow, including the phone and tablet GitHub APK acceptance checklist and the human approval gate before any push, tag, release, or secret change. Android updates always hand off to the system installer; no silent install is promised.

Architecture

Core runtime areas:

• MainActivity.kt - Android platform boundary, WebView host, intents, dashboard Custom Tab handoff
• core/security/ - URL policy and trust-boundary decisions
• data/ - encrypted settings persistence and local state
• domain/ - validation and share-intent parsing
• notification/ - Hermes notification bridge and Android notification presentation
• background/ - reconnect, debug logging, and foreground-service coordination
• server/ - startup preflight and server profile validation/switching
• update/ - Play and GitHub update checks and update UX
• ui/ - Compose screens and ViewModel state

See ARCHITECTURE.md for the detailed runtime flow and security model.

Documentation

• ROADMAP.md - project status, maintenance posture, and wishlist
• ARCHITECTURE.md - runtime flow, boundaries, and extension points
• RELEASE.md - release operator workflow and retry path
• AI_USE.md - AI-assisted development approach, review, validation, and accountability
• AGENTS.md - repository instructions for AI assistants
• assets/ - README images, branding assets, icons, and TWA handoff files

AI-assisted Development

Hermes-Android uses AI-assisted development openly as part of implementation, investigation, and documentation work.

Architecture, security boundaries, validation criteria, and release decisions remain under human ownership. AI output is reviewed as proposed engineering work, not treated as authoritative by default.

See AI_USE.md for the full policy and workflow.