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

On first launch, complete the required Setup Wizard to configure the upstream gateway directly:

Enter the required Remote HTTPS gateway base URL and, optionally, a Local HTTPS URL for the same trusted gateway.
Select no authentication, bearer authentication, or username/password authentication to match the gateway configuration, then enter the required credentials.
Test the connection. The client probes /health, validates compatibility through the authenticated gateway surface, and displays the active Local or Remote route; the wizard finishes only after a successful test.
Exercise chat/session behavior only where the gateway advertises the required capabilities.

After setup completes, Settings reopens the same connection profile for later edits and retesting.

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.

4.5 KiB Raw Permalink Blame History