Hermes Agent
60 lines
2.5 KiB
Markdown
60 lines
2.5 KiB
Markdown
# Companion Server
|
|
|
|
The companion server is a local Fastify HTTP API that the Android app talks to. It runs beside Hermes Agent and keeps Hermes core untouched.
|
|
|
|
## Setup
|
|
|
|
Install dependencies, generate an access key, and start the server:
|
|
|
|
```bash
|
|
npm install
|
|
npm run companion:setup
|
|
npm run companion:dev
|
|
```
|
|
|
|
`npm run companion:setup` runs the local `hermes-mobile-companion setup` command. It creates `~/.config/hermes-mobile/companion.json`, prints the generated `hm_...` access key, and stores the safe workspace root.
|
|
|
|
Useful environment variables:
|
|
|
|
- `PORT` defaults to `8787`.
|
|
- `HOST` defaults to `0.0.0.0` so Android emulators/devices can connect.
|
|
- `HERMES_MOBILE_CONFIG` overrides the config JSON path.
|
|
- `HERMES_MOBILE_ACCESS_KEY` overrides the stored key.
|
|
- `HERMES_MOBILE_WORKSPACE_ROOT` sets the file/terminal allowlisted root.
|
|
|
|
## Pairing
|
|
|
|
1. Run `npm run companion:setup` on the computer running Hermes.
|
|
2. Copy the printed access key.
|
|
3. Open Hermes Mobile Settings.
|
|
4. Use `http://10.0.2.2:8787` for the Android emulator, or `http://<LAN-IP>:8787` for a physical phone on the same network.
|
|
5. Paste the access key and tap **Test connection**.
|
|
|
|
All non-health API requests require:
|
|
|
|
```http
|
|
Authorization: Bearer <access-key>
|
|
```
|
|
|
|
## API
|
|
|
|
- `GET /api/health` returns service, Hermes CLI, auth, uptime, and workspace status.
|
|
- `GET /api/auth/validate` validates the bearer token.
|
|
- `POST /api/chat` accepts `{ "prompt": "..." }` and invokes the local `hermes` CLI when it is on `PATH`.
|
|
- `GET /api/files?path=.` lists files under the configured workspace root.
|
|
- `GET /api/files/read?path=README.md` reads UTF-8 file content.
|
|
- `POST /api/files/write` writes `{ "path": "notes.txt", "content": "..." }` under the workspace root.
|
|
- `GET /api/files/metadata?path=README.md` returns file metadata for download-style clients.
|
|
- `POST /api/terminal/run` runs `{ "command": "pwd && ls", "cwd": ".", "timeoutMs": 10000 }` under the workspace root.
|
|
|
|
## Security Model
|
|
|
|
This is a private LAN/local companion, not an internet-facing service. Security controls are intentionally simple but strict for the MVP:
|
|
|
|
- Bearer token required for every non-health endpoint.
|
|
- File and terminal `cwd` access is constrained to `HERMES_MOBILE_WORKSPACE_ROOT` or the stored setup root.
|
|
- The mobile file explorer hides `.git`, `.dev`, `node_modules`, `dist`, and generated Android build folders.
|
|
- Path traversal outside the root is rejected.
|
|
- Terminal commands run with a configurable timeout capped at 30 seconds.
|
|
- Secrets live in local config or environment variables, never in the repo.
|