Hermes Mobile

Native Android companion app for your Hermes AI agent.

--- ## Overview **Hermes Mobile** is the native Android client for [Hermes Agent](https://hermes-agent.nousresearch.com). It connects securely to your local Hermes gateway (REST API and WebSocket TUI Gateway) over LAN, giving you pocket control over your AI assistant. --- ## Support the project If Hermes Mobile is useful to you, consider supporting its development on [Ko-fi](https://ko-fi.com/m_5_7). --- ## Screenshots

Hermes Mobile chat screen Hermes Mobile cron jobs screen Hermes Mobile Kanban screen Hermes Mobile skills screen

Chat, automation, productivity, and agent configuration — from your phone.

--- ## Features - **Real-Time Chat:** Message your agent with Room-backed local database history and inline reply notifications. - **System Config:** Manage active profiles, installed skills, plugins, toolsets, and LLM model/provider selections. - **Operations:** Stream and filter live logs, manage cron jobs, edit environment keys, test webhooks, and monitor processes. - **Gateway Status:** Monitor WebSocket connection, MCP servers, messaging channels, and OAuth providers. - **Productivity:** View and manage tasks via integrated Kanban boards, track agent milestones, and browse session history. - **Analytics & Billing:** Usage analytics dashboard and billing/subscription management. - **Theming:** 6 built-in color presets (Default, Monochrome, Gruvbox, Catppuccin, AMOLED, Neon Noir) plus Material You dynamic colors on supported devices. - **Modern UX:** Native Material 3 design with pull-to-refresh, scroll-aware TopBar, and customizable bottom navigation. --- ## Quick Start ### Prerequisites - **JDK 21+** (required for Kotlin compilation and the Gradle toolchain) - **Android Studio** (Ladybug+) or a **Nix** development environment ### Build & Deploy 1. **Clone the repository:** ```bash git clone https://github.com/Hy4ri/hermes-mobile.git cd hermes-mobile ``` 2. **Build the debug APK:** ```bash ./gradlew assembleDebug ``` 3. **Install on your emulator/device:** ```bash adb install app/build/outputs/apk/debug/app-debug.apk ``` _Note: For release builds, ensure keystore environment variables (`KEYSTORE_PATH`, `KEYSTORE_PASSWORD`, `KEY_ALIAS`, `KEY_PASSWORD`) are configured, or let the GitHub Actions release workflow handle it on tag push (`v*`)._ --- ## Authentication Once the app is installed, you need to point it at your Hermes gateway. The app auto-detects which auth mode the dashboard is using — just fill in the fields it shows. ### 1. Start the dashboard On your host machine, start the dashboard: ```bash hermes dashboard # loopback (127.0.0.1:9119) — no auth needed hermes dashboard --host 0.0.0.0 # LAN — requires auth ``` For LAN access, configure credentials in `~/.hermes/config.yaml`: ```yaml dashboard: basic_auth: username: admin # pick your own password: hermes # pick your own ``` ### 2. Connect the app Tap **Sign in** on the landing screen and enter the dashboard host and port. The app probes the dashboard and reveals the fields you need: | Auth mode | When | What you fill | | -------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Token only** | Dashboard on same machine (loopback) | **Token** — grab from `~/.hermes/dashboard-token.txt` or `~/.hermes/.env` (`HERMES_DASHBOARD_SESSION_TOKEN`). The app can also auto-extract it from the dashboard page | | **Basic auth** | Dashboard on LAN with password gate | **Username** + **Password** (default `admin` / `hermes`). The app logs in, gets a session cookie, and mints a WebSocket ticket automatically | > The app communicates over plain HTTP — it's designed for **trusted local networks only**. Do not expose your Hermes gateway to untrusted networks. ### Connection profiles Have multiple gateways? Switch between them in **Settings → Connection profiles**. Each profile stores its own host, port, and token — just tap to swap. --- ## Project Structure ``` app/src/main/java/com/m57/hermescontrol/ ├── data/ # Local (Room, AuthManager), Remote (Retrofit, OkHttp), WS (WebSocket), Models ├── notification/ # Foreground service + inline reply for chat notifications ├── theme/ # Preset-based design system (6 themes), status colors, spacing, typography ├── ui/ # 28 Compose feature screens + common components (HermesScaffold, StateViews) ├── util/ # CronExpressionFormatter, LocaleContextWrapper └── Navigation*.kt # Navigation3 wiring, keys, screen registry, controller ``` --- ## Tech Stack - **Language:** Kotlin 2.4.10 with KSP 2.3.10 compiler plugin - **UI & Layout:** Jetpack Compose (BOM 2026.03.01) & Material 3 / Material You - **Navigation:** Navigation3 (Compose-first Routing) - **Networking:** Retrofit 3.0.0, OkHttp 5.4.0, Kotlinx Serialization 1.11.0 - **Database:** Room 2.7.1 with SQLCipher 4.17.0 encryption - **Security:** `EncryptedSharedPreferences` (AES256-GCM), DataStore - **Theming:** 6 built-in presets (Default, Monochrome, Gruvbox, Catppuccin, AMOLED, Neon Noir) + Material You dynamic colors - **Image Loading:** Coil 2.7.0 - **Testing:** JUnit 5, MockK, Turbine, Espresso, Compose UI testing - **Formatting:** `ktlint` 1.8.0 style rules (checked automatically in CI) --- ## Contributing Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for our branch workflow, code style guidelines, and PR checklist. ### Translations Help translate Hermes Mobile into your language on [Hosted Weblate](https://hosted.weblate.org/projects/hermes-mobile/hermes-mobile/)! For developer-specific details, code conventions, and project architecture notes, refer to [AGENTS.md](AGENTS.md). --- ## License Copyright © 2026 M57 (Hy4ri). This project is licensed under the Apache License, Version 2.0. See the [LICENSE](LICENSE) file for details.