Spin up a Matrix-ready box with:
  • PostgreSQL (5432)
  • Synapse client/federation API (8080, bound on 0.0.0.0)

​
Quick Start

zomg matrix create my-matrix
zomg matrix connect-db my-matrix
create waits for Postgres (5432) and Synapse (8080) before returning.

​
Create

zomg matrix create my-matrix
What it sets up:
  • Box tag: service=matrix
  • Single data volume mounted at /var/lib/matrix
  • PostgreSQL data: /var/lib/matrix/postgres
  • Synapse config/state: /var/lib/matrix/synapse
  • Public registration disabled by default (enable_registration: false)
To bind Matrix to a real public name from the start: 
zomg matrix create my-matrix --hostname chat.example.com
This publishes the box at chat.example.com and initializes Synapse with:
  • server_name: chat.example.com
  • public_baseurl: https://chat.example.com/

​
Connect (Postgres)

zomg matrix connect-db my-matrix
Pass extra psql args after --: 
zomg matrix connect-db my-matrix -- -c "select now()"
Defaults:
  • User: postgres
  • Database: postgres
  • Password: postgres

​
Create User (Admin Path)

With public registration disabled, create users via the service command: 
zomg matrix new-user my-matrix alice --password 'dev-pass'
zomg matrix new-user my-matrix admin --password 'admin-pass' --admin
This runs inside the box and uses Synapse admin registration tooling.

​
Get Access Token

zomg matrix get-access-token my-matrix \
  --user '@alice:chat.example.com' \
  --password 'dev-pass'
This logs in via /_matrix/client/v3/login and prints only the access token. By default it uses the first published domain for the matrix box, then falls back to Box API URL metadata. Use an explicit hostname or URL: 
zomg matrix get-access-token my-matrix \
  --hostname chat.example.com \
  --user '@alice:chat.example.com' \
  --password 'dev-pass'

zomg matrix get-access-token my-matrix \
  --url https://chat.example.com \
  --user '@alice:chat.example.com' \
  --password 'dev-pass' \
  --json

​
Matrix API Smoke Check

zomg exec my-matrix --project <project> -- \
  curl -fsS http://127.0.0.1:8080/_matrix/client/versions

​
Public URL Smoke Check

zomg list --project <project>
# then hit the box URL from list:
curl -fsS "https://<box-url-from-list>/_matrix/client/versions"
Synapse client discovery (/.well-known/matrix/client) advertises this public URL. The initial value comes from Box API url metadata (box/domain aware).

​
Publish (Custom Public Name)

zomg matrix publish my-matrix my-chat
This:
  • runs zomg publish
  • resolves the real published hostname from Box API metadata
  • updates Synapse public_baseurl so /.well-known/matrix/client points at the published URL.
With explicit domain override: 
zomg matrix publish my-matrix my-chat --domain example.com
Or publish directly to an exact hostname: 
zomg matrix publish my-matrix --hostname chat.example.com

​
Snapshot + Clone

zomg matrix snapshot my-matrix
zomg matrix create my-matrix-copy --fork my-matrix
Postgres and Synapse state snapshot and restore together since they share one mounted data volume.

​
Stop

zomg matrix stop my-matrix
Performs clean stops for:
  • Synapse process
  • PostgreSQL (CHECKPOINT + smart shutdown)

​
E2E Verification (Bot + Room + Second Instance)

Run: 
./crates/zomg-matrix/verify.sh
This verifies real usage, not just infra plumbing:
  1. Creates matrix-A and confirms Matrix API is live.
  2. Creates bot and human users via zomg matrix new-user.
  3. Bot creates a room and sends a message.
  4. Human user reads the event from the room.
  5. Clones to matrix-B.
  6. Bot logs into the second instance and sends another message.
  7. Human user on the second instance reads both the pre-clone and post-clone messages.
It also validates zomg matrix list tag filtering and zomg matrix delete cleanup.