Back to Tutorials
Tutorial 2 of 6 · Matrix Setup

Matrix Setup — Continuwuity + Hermes Gateway

Matrix protocol integration: Continuwuity homeserver, LCAgent Gateway, bot provisioning, rooms, and slash commands.

Next: BOM & Product LCA

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

ServiceRolePorts
continuwuityRust-based Matrix homeserver — client-server & federation APIs8008 (client-server), 8448 (federation)
lcagent-gatewaymautrix SDK + Hermes Agent bridge — scope enforcement, profile routing8000 (REST API & health)

Gateway Environment Variables

VariableExamplePurpose
MATRIX_HOMESERVER_URLhttps://matrix.lca.localHomeserver URL
MATRIX_BOT_USER_ID@lcagent:matrix.lca.localBot Matrix ID
MATRIX_BOT_PASSWORD***Bot password (secret)
MATRIX_REGISTRATION_TOKEN***Registration token (secret)
MATRIX_INTERNAL_URLhttp://continuwuity:8008Internal homeserver URL
DATABASE_URL***PostgreSQL URL
OAUTH_CLIENT_ID / OAUTH_CLIENT_SECRET***Application API auth
SECRET_KEY***JWT signing secret (≥32 bytes)
LLM_MODELmeta-llama/llama-3.1-8b-instruct:freeDefault LLM model
REDIS_URLredis://redis:6379/0Caching & 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

RoomPurposeAccess
#generalGeneral discussionAdmin-controlled
#devDevelopmentAdmin-controlled
#financialFinancial dataAdmin-controlled
#lcaLCA calculationsAdmin-controlled
#marketingMarketingAdmin-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)

CommandPurpose
/goal <objective>Initialize a long-running autonomous goal loop
/subgoal <description>Append a milestone to the active goal
/stopHalt and terminate the active agent loop
/steer <instruction>Real-time course correction to the running loop
/newReset 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

SkillTriggerCapability
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