hermes-mobile/docs/ANDROID_BETA_BUILD.md

Android Beta Build and Install

This guide covers the native Kotlin/Compose direct-gateway client at version v0.1.0-beta.1. It does not build or require apps/companion, publish an APK, or complete the beta release criteria by itself.

Package identity

• Application ID: cloud.molberg.hermesmobile
• Android versionName: 0.1.0-beta.1
• Android versionCode: 10001
• Debug APK: apps/mobile/android/app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk

versionName is the user-visible semantic version. versionCode is an internal monotonically increasing Android package revision and must increase for every later installable build.

Prerequisites

• JDK 17 or newer supported by the checked-in Android Gradle Plugin.
• Android SDK platform 35, matching build tools, and platform tools.
• Network access for the first dependency resolution, or a complete compatible Gradle cache.
• For installation, a real Android device with USB debugging enabled or a running emulator visible to adb.
• For use, an HTTPS upstream Hermes Agent gateway/API server and its bearer token when authentication is enabled.

Do not run Capacitor synchronization for this client. The beta application source is the native project under apps/mobile/android.

Build and test

From the repository root:

cd apps/mobile/android
GRADLE_USER_HOME="$PWD/../../../.gradle-user" ./gradlew \
  :app:testDebugUnitTest \
  :app:assembleDebug

The expected APK is:

app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk

Confirm the package metadata before distributing the file:

aapt dump badging app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk \
  | sed -n '1p'
sha256sum app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk

Expected badging includes package cloud.molberg.hermesmobile, versionCode='10001', and versionName='0.1.0-beta.1'.

The debug APK is signed with the local Android debug key. It is suitable for beta verification, not a production signing or store-release workflow. APKs and build output must remain untracked.

Clean install and run

Confirm that exactly one intended target is attached:

adb devices -l

Remove any prior installation, then install the newly built APK. Uninstalling clears existing Hermes Mobile app data and stored gateway credentials.

adb uninstall cloud.molberg.hermesmobile || true
adb install app/build/outputs/apk/debug/hermes-mobile-v0.1.0-beta.1-debug.apk
adb shell monkey -p cloud.molberg.hermesmobile -c android.intent.category.LAUNCHER 1

In Hermes Mobile Settings, configure the upstream gateway directly:

1. Enter the required Remote HTTPS gateway base URL and, optionally, a Local HTTPS URL for the same trusted gateway.
2. Select bearer authentication and enter the gateway token when required, or select no authentication only when the gateway is configured that way.
3. Save and test the connection. The client probes /health, validates compatibility through the authenticated gateway surface, and displays the active Local or Remote route.
4. Exercise chat/session behavior only where the gateway advertises the required capabilities.

Do not enter a legacy companion URL or companion access key. The beta path is the direct upstream Hermes gateway architecture described in docs/DIRECT_GATEWAY_ARCHITECTURE.md.

Required install evidence

Record all of the following before claiming R2 installation verification or a beta release:

• The source commit used for the build.
• Passing Android unit tests and APK assembly.
• aapt package/version output and the APK SHA-256.
• A successful clean adb install on a named real device or emulator.
• App launch plus direct-gateway configuration and connection result.
• Any observed limitations or failures, without treating source-only checks as device evidence.

Known limitations

• R1 adaptive/accessibility verification still requires the documented real-device/emulator matrix.
• B3 remains blocked on an official session-search contract and live upstream gateway compatibility evidence.
• Direct gateway chat, streaming, tools, artifacts, and recovery remain capability-gated; unsupported or unverified routes are not inferred.
• The debug APK is not a published release artifact. No beta release exists until all release criteria in docs/ROADMAP.md are genuinely satisfied.