This page documents the MatrixBot product site. The commands and security notes below match the self-hosted v0.4.0 build; the numbers come from the instance running on this machine, and the product is currently in closed beta. The full project README lives in the source repository.

Quick start

Node.js 22 or newer is required. The first start creates an admin account and prints the initial password once in the startup log; you can also set MAC_ADMIN_PASSWORD in .env beforehand.

git clone <repo-url> matrixbot
cd matrixbot
cp .env.example .env      # adjust ports, models and file roots as needed
npm install
npm run build
npm start                 # http://127.0.0.1:8790

Development mode runs the backend with hot reload plus Vite: npm run dev. With Docker:

docker compose up -d --build
docker compose logs matrixbot | grep initial password

After signing in, change the password under Account, then add runtimes or model endpoints under Settings → Connections.

Connect a runtime

A connection is the boundary between MatrixBot and an agent: it decides which machine the session runs on, which tools it can call, and whether dangerous commands need approval.

Type	Capability	Address example
Hermes	Full agent capability: tools, approval, interruption, sub-agents, channels	http://host:8642
OpenCode	Code and file workflows, session resume	http://host:4096
dsh	Command-line agent runtime for local automation	local process
ACP	Agent Client Protocol compatible runtime	per runtime config
OpenAI compatible	Chat only: streaming, reasoning trace, multi-turn context	https://api.example.com/v1

One agent binds to one connection. Enter the address and key, then hit Test to list available models; health is visible in settings.

Deploy behind a reverse proxy

Put MatrixBot behind an HTTPS reverse proxy and bind only to loopback. Browser microphones, cross-device sign-in and multiple users all require HTTPS.

# .env
PORT=8790
HOST=127.0.0.1
MAC_DEFAULT_USER=admin
MAC_ADMIN_PASSWORD=<set a strong password>
FILE_ROOTS=$HOME:/tmp

The proxy must disable response buffering for SSE streaming and raise the request body limit for uploads. Proxied requests always require sign-in; never enable MAC_TRUST_LOOPBACK in production.

Security model

Worth reading before you open an instance to anyone else. This is usage boundary, not marketing copy.

Hermes executes commands as a system account. Sharing a Hermes connection means the other person can act on that machine. Share only with people you trust, or deploy a separate runtime per person.
Approval is not a sandbox. Approval only covers commands the runtime flags as dangerous; shared connections can be set to always deny.
Regular users are isolated by default. They cannot see local memory, logs, scheduled tasks, skills or projects; cannot see other people's conversations, runtime state or screen; and cannot read home directory files.
Sensitive files are never exposed. Databases, key files and the data/ directory are not served through the file API to anyone, admins included.
Actions leave a trace. Sign-ins, account and sharing changes, messages (length only), approvals and stops all go to the audit log.

Backup and upgrade

The database lives in the data directory, one SQLite file per user. Before upgrading, stop the service, copy the data directory and .env, then pull the new version and run npm install && npm run build. Rolling back means restoring the previous data directory and switching back to the previous build.

This project is MIT licensed. Report security issues privately rather than opening a public issue.

Back to home Join beta