Hermes Agent
119 lines
3.4 KiB
Markdown
119 lines
3.4 KiB
Markdown
# Hermes Mobile
|
|
|
|
Android-first mobile control surface and local companion server for [Hermes Agent](https://github.com/NousResearch/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
|
|
|
|
```text
|
|
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:
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
## Companion Setup and Run
|
|
|
|
Generate/persist a local access key:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
npm run companion:dev
|
|
```
|
|
|
|
The server listens on `0.0.0.0:8787` by default. Useful overrides:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
npm run cap:add:android --workspace @hermes-mobile/mobile
|
|
npm run android:build:debug --workspace @hermes-mobile/mobile
|
|
```
|
|
|
|
APK output:
|
|
|
|
```text
|
|
apps/mobile/android/app/build/outputs/apk/debug/app-debug.apk
|
|
```
|
|
|
|
For later rebuilds after the native project exists:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Docs
|
|
|
|
- [Companion Server](docs/COMPANION_SERVER.md)
|
|
- [Mobile App Structure](docs/MOBILE_APP.md)
|
|
- [Architecture](docs/ARCHITECTURE.md)
|
|
- [Product Plan](docs/PRODUCT_PLAN.md)
|
|
- [Install Strategy](docs/INSTALL.md)
|
|
- [Testing Strategy](docs/TESTING.md)
|
|
- [Roadmap](docs/ROADMAP.md)
|