rousseau matrix

Overview

rousseau matrix runs the Matrix client-server bridge. The daemon long-polls /sync on a homeserver, routes each incoming m.room.message from a non-self sender through the agent, and posts replies via /rooms/{room}/send/m.room.message. Works against matrix.org or any self-hosted Synapse / Dendrite / Conduit / Conduwuit instance.

Source: internal/cli/matrix.go. Transport: internal/transport/matrix/.

Synopsis

rousseau matrix [--homeserver <url>] [--token <access-token>] [--user-id <mxid>] [--allow <mxid>...]

Flags

Config keys respected

internal/config/config.go MatrixConfig:

Key	Type	Default	Effect
matrix.homeserver_url	string	empty	Base URL.
matrix.access_token	string	empty	Bot access token.
matrix.user_id	string	empty	Bot MXID (@rousseau-bot:example.com).
matrix.reply_header	string	empty	Prefix on outbound messages.
matrix.allowlist	[]string	empty	MXIDs allowed to converse.

Allowlist syntax

Every entry is a fully-qualified MXID:

matrix:
  allowlist:
    - "@alice:example.com"
    - "@bob:matrix.org"

Room-level allowlisting is not currently supported; use user MXIDs.

Environment variables

Variable	Effect
ROUSSEAU_MATRIX_HOMESERVER_URL	Overrides homeserver URL.
ROUSSEAU_MATRIX_ACCESS_TOKEN	Overrides access token.
ROUSSEAU_MATRIX_USER_ID	Overrides bot MXID.

Startup sequence

1. Resolve homeserver + token; fail if either is empty.
2. Default claudecli.permission_mode to bypassPermissions.
3. Open session store; build agent wiring.
4. matrix.New — instantiate the client.
5. wiring.startCron — cron delivery via room send API.
6. /sync long-poll loop until context cancelled.

Exit codes

Code	Meaning
0	Clean context cancellation.
1	Missing homeserver/token, HTTP error, provider/store failure.
130	SIGINT.

Worked examples

# Public matrix.org bot
rousseau matrix \
  --homeserver https://matrix.org \
  --token syt_… \
  --user-id "@rousseau-bot:matrix.org" \
  --allow "@alice:matrix.org"

# Self-hosted Synapse
cat > ~/.config/rousseau/config.yaml <<'EOF'
matrix:
  homeserver_url: "https://matrix.internal.example"
  access_token: "syt_…"
  user_id: "@rousseau-bot:internal.example"
  allowlist:
    - "@alice:internal.example"
    - "@bob:internal.example"
EOF
rousseau matrix

Common failure modes

• M_UNKNOWN_TOKEN — access token expired or revoked. Re-login the bot user.
• M_LIMIT_EXCEEDED — homeserver rate-limited the sync loop. Back off.
• Bot answers its own messages — set --user-id so own-message loop prevention works.
• Silent inbound drops — sender MXID not on the allowlist.

Related pages

• Transports: Matrix
• Recipes: Matrix room monitor
• Best Practices: Secret management
• Reference: Logs