Tutorial 2 of 6 · Matrix Setup
Matrix Setup — Continuwuity + Hermes Gateway
Matrix protocol integration: Continuwuity homeserver, LCAgent Gateway, bot provisioning, rooms, and slash commands.
Architecture Overview
`Matrix Client ↔ Matrix Homeserver (Continuwuity) ↓ (mautrix sync) LCAgent Gateway (mautrix Python SDK) ↓ (scope enforcement + profile routing) Hermes Agent (per-profile instance) ↓ (tool execution) Application API / Codebase`
Two independently scalable Docker services:
Service Components
| Service | Role | Ports |
|---|---|---|
| continuwuity | Rust-based Matrix homeserver — client-server & federation APIs | 8008 (client-server), 8448 (federation) |
| lcagent-gateway | mautrix SDK + Hermes Agent bridge — scope enforcement, profile routing | 8000 (REST API & health) |
Gateway Environment Variables
| Variable | Example | Purpose |
|---|---|---|
| MATRIX_HOMESERVER_URL | https://matrix.lca.local | Homeserver URL |
| MATRIX_BOT_USER_ID | @lcagent:matrix.lca.local | Bot Matrix ID |
| MATRIX_BOT_PASSWORD | *** | Bot password (secret) |
| MATRIX_REGISTRATION_TOKEN | *** | Registration token (secret) |
| MATRIX_INTERNAL_URL | http://continuwuity:8008 | Internal homeserver URL |
| DATABASE_URL | *** | PostgreSQL URL |
| OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET | *** | Application API auth |
| SECRET_KEY | *** | JWT signing secret (≥32 bytes) |
| LLM_MODEL | meta-llama/llama-3.1-8b-instruct:free | Default LLM model |
| REDIS_URL | redis://redis:6379/0 | Caching & ontology batch queuing |
Bot Identity
Bot user ID
@lcagent:matrix.lca.local
Bot username
lcagent
Registration token
Required (set via MATRIX_REGISTRATION_TOKEN)
The gateway auto-registers the bot account on startup if it doesn't exist, sending the registration token inside the auth block (UIA stage). If the account already exists, registration is skipped and login proceeds.
Five Default Rooms & Access Control
| Room | Purpose | Access |
|---|---|---|
| #general | General discussion | Admin-controlled |
| #dev | Development | Admin-controlled |
| #financial | Financial data | Admin-controlled |
| #lca | LCA calculations | Admin-controlled |
| #marketing | Marketing | Admin-controlled |
Room membership is managed exclusively by the .env admin via the Room Permissions tab in the Hermes settings interface. Users may create additional rooms beyond the five defaults.
Autonomous Agent Commands (.env Admin Only)
| Command | Purpose |
|---|---|
| /goal <objective> | Initialize a long-running autonomous goal loop |
| /subgoal <description> | Append a milestone to the active goal |
| /stop | Halt and terminate the active agent loop |
| /steer <instruction> | Real-time course correction to the running loop |
| /new | Reset session history and clear active goal state |
| /model [model_name] | Inspect or switch the active LLM model |
These slash commands are restricted via RBAC to the system .env admin (@admin_corporate.com:matrix.lca.local).
Hermes Skills & Prompts
| Skill | Trigger | Capability |
|---|---|---|
| db-query-records | !bot records <table> | Dynamic PostgreSQL table queries with RBAC |
| sql-executor | !bot sql SELECT ... | Read-only SQL execution (no INSERT/UPDATE/DELETE) |
| sparql-query-builder | !bot sparql <subject> | Oxigraph RDF triplestore queries |
| bom-lineage-query | !bot lineage <sku> | Supply chain lineage trace |