Hero MatrixChat

Admin toolkit for Matrix homeservers. Connect to one or more Matrix servers (Conduit, Synapse, Dendrite, etc.) through profile-based configuration and manage users, rooms, spaces, and messages from a single CLI, web dashboard, or JSON-RPC API.

What it does

• Multi-profile — define any number of Matrix server connections in ~/hero/cfg/matrix/*.toml, switch between them from the CLI (--profile) or the UI dropdown
• User management — list, create, delete users and reset passwords via the Matrix CS API
• Room & space management — list public/joined rooms, create rooms and spaces, inspect state, manage members
• Messaging — send and retrieve messages, typing notifications, sync
• Server monitoring — health checks, server version, user/room counts per profile
• Web dashboard — Bootstrap 5 dark-themed admin UI at http://127.0.0.1:3790 with live profile switching
• JSON-RPC server — all operations available over a Unix socket for tool integration
• Rhai scripting — automate any operation from Rhai scripts

Architecture

hero_matrixchat/
├── crates/
│ ├── hero_matrixchat_sdk/ # SDK: MatrixClient (CS API), ProfileManager, types
│ ├── hero_matrixchat_server/ # JSON-RPC daemon on Unix socket
│ ├── hero_matrixchat/ # CLI
│ ├── hero_matrixchat_admin/ # Axum web dashboard
│ └── hero_matrixchat_rhai/ # Rhai scripting bindings

~/hero/cfg/matrix/ # Profile configs (one .toml per server)
~/hero/var/sockets/ # Unix sockets for server + UI

All four binaries depend only on the SDK crate:

hero_matrixchat_sdk
 ↑ ↑ ↑ ↑
 server CLI UI rhai

The SDK talks directly to Matrix servers over HTTP using the Client-Server API — no custom protocol involved.

Quick start

# 1. Create a profile (assumes a Matrix server on localhost:6167)
mkdir ~/hero/cfg/matrix
"server_url = \"http://127.0.0.1:6167\"\nusername = \"@admin:localhost\"\npassword = \"admin_password\"\nregistration_token = \"conduit_dev_token\"\n" | save ~/hero/cfg/matrix/local.toml

# 2. Start (builds and installs automatically on first run)
service matrixchat start --update --reset

# 3. Stop / reset
service matrixchat stop
service matrixchat start --update --reset

If no profile files exist, an implicit local profile pointing to 127.0.0.1:6167 is created automatically.

CLI usage

hero_matrixchat health # check server connectivity
hero_matrixchat users list # list users on default profile
hero_matrixchat --profile work users list # list users on "work" profile
hero_matrixchat users create --username alice --password secret
hero_matrixchat rooms list
hero_matrixchat send --room-id '!abc:example.com' --message "hello"
hero_matrixchat messages --room-id '!abc:example.com' --limit 20
hero_matrixchat stats
hero_matrixchat profiles list

Profile configuration

Each .toml file in ~/hero/cfg/matrix/ defines one Matrix server connection. The filename (without extension) becomes the profile name.

# ~/hero/cfg/matrix/work.toml
server_url = "https://matrix.example.com"
username = "@admin:example.com"
password = "secret"
registration_token = "optional_registration_token"

Field	Required	Description
server_url	yes	Base URL of the Matrix server
username	yes	Matrix user ID or local part
password	yes	Password for login
registration_token	no	Token for creating new users via the registration API

Ports and sockets

Component	Socket	Path
hero_matrixchat_server	rpc.sock	$PATH_SOCKET/hero_matrixchat/rpc.sock
hero_matrixchat_admin	web.sock	$PATH_SOCKET/hero_matrixchat/web.sock

JSON-RPC methods

All methods accept an optional profile parameter. When omitted, the first profile (alphabetically) is used.

Method	Description
health	Server version, reachability, server name
list_users	Search the user directory
create_user	Register a new user
delete_user	Deactivate a user
reset_password	Reset a user's password
list_rooms	Public and joined rooms with member counts
send_message	Send a text message to a room
get_messages	Retrieve messages from a room
server_stats	Aggregate stats (user count, room count, version)
list_profiles	Available profile names
get_config	Read server-level configuration
update_config	Write server-level configuration

Service management (nushell — preferred)

service matrixchat start --update --reset # build, install, and start
service matrixchat stop # stop all service processes
service matrixchat status # show running state

Make targets (legacy — kept for CI compatibility)

make help Show all targets
make build Build all crates (release)
make check Fast workspace check (no build)
make test Unit tests
make test-integration SDK integration tests (needs running Matrix server)
make test-all Full test suite
make fmt Format code
make lint Run clippy
make install Build and install to ~/hero/bin

Testing

Integration tests talk directly to a Matrix server via the CS API — they register users, create rooms and spaces, send messages, and verify everything round-trips correctly.

# Requires a Matrix server on 127.0.0.1:6167 with registration enabled
make test-integration

# Unit tests only (no server required)
make test

# Everything
make test-all