docs: initial wiki page

2026-05-23 11:40:14 -04:00
parent 2e7559e5f2
commit d5eefcb6a3
1 changed files with 65 additions and 0 deletions
@@ -0,0 +1,65 @@
+# Matrix-Hermes
+
+Matrix bridge for Hermes Agent — provides authentication, client connectivity, and bridge utilities.
+
+## Quick Start
+
+```bash
+cd ~/projects/matrix-hermes
+pip install -e ".[dev]"
+cp .env.example .env
+# Edit .env with your Matrix credentials
+matrix-hermes check
+matrix-hermes login
+```
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `MATRIX_HOMESERVER` | Homeserver URL (e.g. https://matrix.org) | Yes |
+| `MATRIX_ACCESS_TOKEN` | Existing access token (preferred) | Yes* |
+| `MATRIX_USER_ID` | Full Matrix user ID (@user:server) | Yes* |
+| `MATRIX_PASSWORD` | Password for login | Yes* |
+| `MATRIX_DEVICE_ID` | Stable device ID for E2EE | No |
+| `MATRIX_SESSION_DIR` | Session persistence dir | No |
+| `MATRIX_ENCRYPTION` | Enable E2EE (true/false) | No |
+| `MATRIX_ALLOWED_USERS` | Comma-separated user whitelist | No |
+| `MATRIX_HOME_ROOM` | Room ID for notifications | No |
+
+*Either MATRIX_ACCESS_TOKEN or MATRIX_USER_ID + MATRIX_PASSWORD is required.
+
+## Authentication Flow
+
+1. **Access token** — if `MATRIX_ACCESS_TOKEN` is set, it's validated via `/whoami`
+2. **Session file** — if no token, checks `~/.hermes/matrix_sessions/<user>.json`
+3. **Password login** — falls back to `MATRIX_USER_ID` + `MATRIX_PASSWORD`; token auto-saved
+
+## CLI Commands
+
+```bash
+matrix-hermes login      # Authenticate with homeserver
+matrix-hermes whoami     # Validate current token
+matrix-hermes logout     # Invalidate token + remove session
+matrix-hermes check      # Check config from env
+matrix-hermes show-config # Show config as env vars
+```
+
+## Project Structure
+
+```
+src/matrix_hermes/
+├── __init__.py   # Package init
+├── auth.py       # Login, token, session persistence
+├── client.py     # Async MatrixClient (mautrix wrapper)
+├── config.py     # Env-based configuration
+└── cli.py        # CLI entry point
+tests/            # 60 unit tests
+```
+
+## Dependencies
+
+- Python >= 3.10
+- mautrix >= 0.20.0
+- aiohttp >= 3.9
+- python-dotenv >= 1.0