Matrix

mautrix-go

Primary library for production Matrix bots and bridges in Go. All active mautrix development targets Go; Python bridge module is officially deprecated.

Build with -tags goolm — pure Go olm implementation, no CGo, no libolm dependency. Required for static Kubernetes binaries, distroless images, and multi-arch cross-compilation.

Client and Crypto Setup

package main

import (
    "context"
    "os"

    "github.com/rs/zerolog/log"
    "maunium.net/go/mautrix"
    "maunium.net/go/mautrix/crypto/cryptohelper"
    "maunium.net/go/mautrix/event"
    "maunium.net/go/mautrix/id"
)

func main() {
    ctx := context.Background()

    // pickleKey encrypts olm account and session blobs at rest.
    // Store in a Kubernetes Secret — losing it requires full E2EE state reset.
    pickleKey := []byte(os.Getenv("MATRIX_PICKLE_KEY"))

    cli, err := mautrix.NewClient("https://matrix.example.com", "@bot:example.com", "")
    if err != nil {
        log.Fatal().Err(err).Msg("matrix client init failed")
    }

    // Pass Postgres DSN or SQLite file path — both supported natively.
    // Never inline credentials — read DSN from an environment variable or secret manager.
    helper, err := cryptohelper.NewCryptoHelper(cli, pickleKey, os.Getenv("MATRIX_DB_DSN"))
    if err != nil {
        log.Fatal().Err(err).Msg("crypto helper init failed")
    }

    helper.LoginAs = &mautrix.ReqLogin{
        Type:             mautrix.AuthTypePassword,
        Identifier:       mautrix.UserIdentifier{Type: mautrix.IdentifierTypeUser, User: "bot"},
        Password:         os.Getenv("MATRIX_PASSWORD"),
        StoreCredentials: true,
    }

    // Init: upgrades DB schema, shares OLM keys, registers sync handlers automatically
    if err := helper.Init(ctx); err != nil {
        log.Fatal().Err(err).Msg("crypto init failed")
    }
    cli.Crypto = helper  // enables auto-encrypt on send, auto-decrypt on receive

    // ... continued in Event Handling and Sync Loop below — do not close func main() here

Event Handling and Sync Loop

This snippet is the direct continuation of func main() above. In practice both sections form a single function; they are split here for readability.

    syncer, ok := cli.Syncer.(*mautrix.DefaultSyncer)
    if !ok {
        log.Fatal().Msg("unexpected syncer type — ensure no custom Syncer is installed before this call")
    }

    // Server-side self-filter (preferred — reduces sync payload size)
    syncer.FilterJSON = &mautrix.Filter{
        Room: mautrix.RoomFilter{
            Timeline: mautrix.FilterPart{
                NotSenders: []id.UserID{cli.UserID},
            },
        },
    }

    // Handler receives already-decrypted events transparently when cli.Crypto is set
    syncer.OnEventType(event.EventMessage, func(ctx context.Context, evt *event.Event) {
        content := evt.Content.AsMessage()
        log.Info().Str("room", evt.RoomID.String()).Str("text", content.Body).Msg("received")
    })

    // Decryption failure hook — log and optionally notify room
    helper.DecryptErrorCallback = func(evt *event.Event, err error) {
        log.Warn().Err(err).Str("event_id", evt.ID.String()).Msg("decryption failed")
    }

    // Send startup message before the blocking sync loop begins.
    // In production, outbound sends are typically triggered inside event handlers.
    // roomID is obtained from an invite event, Join response, or hardcoded for known rooms.
    roomID := id.RoomID("!example:example.com") // placeholder — replace with real room ID
    if _, err := cli.SendText(ctx, roomID, "Hello from voice bot"); err != nil {
        log.Error().Err(err).Msg("send failed")
    }

    // SyncWithContext blocks — runs indefinitely with exponential backoff.
    // Cancel ctx (e.g. via os/signal) to shut down cleanly.
    if err := cli.SyncWithContext(ctx); err != nil && err != context.Canceled {
        log.Error().Err(err).Msg("sync loop exited")
    }
}

SQLCryptoStore Persistence

• PostgreSQL (recommended for production): pass a Postgres DSN or *dbutil.Database to NewCryptoHelper. Tables prefixed crypto_ are created automatically.
• SQLite (single-pod / dev): pass a file path string — uses WAL mode automatically. One pod only.
• Schema is versioned with 19 migrations; auto-applied on Init().
• Never share the bot database with another program. Each bot instance must own its own crypto_* tables.

self_sign — Required from April 2026

• Bots cannot perform interactive verification (QR/emoji). self_sign: true generates and self-signs cross-signing keys automatically on first Init().
• Without it, well-configured clients will stop encrypting to the bot's device after April 2026 (MSC4350 client enforcement).
• Must be configured before the first helper.Init() call — cross-signing keys are generated once and persisted; retrofitting them into an existing OlmAccount is not supported.

Tuwunel Operations

Tuwunel is a Conduit-family homeserver (Rust). Conduit-family servers are explicitly named as supported by mautrix. Go bots/bridges require no manual bot account registration on Conduit-family homeservers (unlike Python bridges, which do).

TOML Configuration

Config file: tuwunel.toml (or tuwunel-example.toml for reference). All keys live under [global].

[global]
server_name = "example.com"         # REQUIRED — cannot be changed after DB creation
database_path = "/var/lib/tuwunel"  # data + media directory
address = ["0.0.0.0"]               # listening address (string or array)
port = 8008                          # listening port (int or array)
allow_registration = false           # disable open registration by default
registration_token = "secure_token"  # static registration token
log = "info"                         # tracing-subscriber syntax: "info,tuwunel_core=debug"
allow_encryption = true              # E2EE enabled (default: true)
allow_federation = true              # federation enabled (default: true)

Environment Variable Overrides

• Prefix: TUWUNEL_ (also accepts legacy CONDUWUIT_, CONDUIT_)
• Nested config keys use __ (double underscore) separator

TUWUNEL_SERVER_NAME=example.com
TUWUNEL_DATABASE_PATH=/var/lib/tuwunel
TUWUNEL_PORT=8008
TUWUNEL_ALLOW_REGISTRATION=false
TUWUNEL_REGISTRATION_TOKEN=secure_token
TUWUNEL_LOG=info
# Nested: [global.tls]
TUWUNEL_TLS__CERTIFICATE_PATH=/etc/tuwunel/cert.pem

Admin Room Commands

All admin commands are sent as messages in the #admins:example.com room.

Appservice Registration

Send appservice_register as a plain message in the admin room, then immediately follow it with a separate YAML code block message:

appservice_register