Hermes Mobile

Native Android companion app for your Hermes AI agent.

---

Overview

Hermes Mobile is the native Android client for Hermes Agent. 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.

---

Screenshots

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:

   git clone https://github.com/Hy4ri/hermes-mobile.git
   cd hermes-mobile
   

2. Build the debug APK:

   ./gradlew assembleDebug
   

3. Install on your emulator/device:

   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*).

Nix emulator

The Nix development shell enables physical keyboard input in an existing hermes_dev AVD configuration. It respects ANDROID_AVD_HOME and ANDROID_USER_HOME, defaulting to ~/.android/avd.

Close any running emulator, then cold boot once to apply the setting:

nix develop --command emulator -avd hermes_dev -no-snapshot-load

Subsequent launches can omit -no-snapshot-load. Create the hermes_dev AVD first if it does not exist; the shell does not create one.

---

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:

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:

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:

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 for our branch workflow, code style guidelines, and PR checklist.

Translations

Help translate Hermes Mobile into your language on Hosted Weblate!

For developer-specific details, code conventions, and project architecture notes, refer to AGENTS.md.

---

License

Copyright © 2026 M57 (Hy4ri).

This project is licensed under the Apache License, Version 2.0. See the LICENSE file for details.