# 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.