Hermes Mobile

Android-first mobile control surface and local companion server for Hermes Agent.

Hermes Mobile is a self-hosted phone UI for running Hermes from Android: chat prompts, browse/edit workspace files, run terminal commands, and check companion/Hermes status over a simple HTTP API.

What Works Now

Vite React mobile app with Chat, Files, Terminal, Status, and Settings screens.
Capacitor configuration and scripts for generating/building an Android APK.
Fastify companion server with bearer-token auth and safe workspace-root file/terminal access.
Local setup command that generates and persists an access key.
HTTP API communication between the mobile app and companion server.

Monorepo

apps/mobile       Vite React + Capacitor Android app
apps/companion    Fastify local companion server
packages/shared   Shared TypeScript API schemas/types
docs              Product, architecture, install, and API notes

Install Dependencies

This repo works with npm workspaces:

npm install

Companion Setup and Run

Generate/persist a local access key:

npm run companion:setup

The command prints:

Config path, normally ~/.config/hermes-mobile/companion.json
Safe workspace root
Access key such as hm_...

Start the companion server:

npm run companion:dev

The server listens on 0.0.0.0:8787 by default. Useful overrides:

PORT=8787 HOST=0.0.0.0 HERMES_MOBILE_WORKSPACE_ROOT=/path/to/workspace npm run companion:dev

All non-health endpoints require Authorization: Bearer <access-key>.

Mobile Development

Run the browser/PWA development shell:

npm run mobile:dev

Open Settings in the app and use:

Android emulator URL: http://10.0.2.2:8787
Physical device URL: http://<your-computer-lan-ip>:8787
Access key: value printed by npm run companion:setup

Tap Test connection to validate the server and key.

Android APK Build

Install Android Studio/SDK/JDK, then generate the native Android project and build a debug APK:

npm run cap:add:android --workspace @hermes-mobile/mobile
npm run android:build:debug --workspace @hermes-mobile/mobile

APK output:

apps/mobile/android/app/build/outputs/apk/debug/app-debug.apk

For later rebuilds after the native project exists:

npm run cap:sync --workspace @hermes-mobile/mobile
cd apps/mobile/android
./gradlew assembleDebug

Companion API

GET /api/health — no token required; returns service, Hermes CLI, workspace, and uptime.
GET /api/auth/validate — validates Authorization: Bearer <key>.
POST /api/chat — sends { "prompt": "..." } to local hermes CLI when available.
GET /api/files?path=. — lists workspace files/directories.
GET /api/files/read?path=README.md — reads UTF-8 file content.
POST /api/files/write — writes { "path": "notes.txt", "content": "..." }.
GET /api/files/metadata?path=README.md — returns download-style file metadata.
POST /api/terminal/run — runs { "command": "pwd && ls", "cwd": ".", "timeoutMs": 10000 } under the workspace root.

3.4 KiB Raw Blame History