hermes-mobile/docs/COMPANION_SERVER.md

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:

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:

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.