Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Introduction

Welcome to the gomuks docs!

Discussion

Matrix room: #gomuks:maunium.net

Installation

There is a demo instance of gomuks web compiled to wasm available at https://demo.gomuks.app. However, the performance is significantly worse than with a native backend, so the demo is only meant for testing with a small account.

The Android wrapper does not currently come with the backend, which means you have to run the backend elsewhere. Something like a Raspberry Pi plus Tailscale (or another Wireguard solution) for external connectivity usually works nicely.

New gomuks terminal currently requires the backend to be running separately. An embedded backend mode will be added later. It also doesn't support Matrix login yet, so the backend must be set up using the web frontend before the terminal frontend can be used.

Installing a package

The releases on GitHub contain binaries and debian packages for legacy gomuks terminal: https://github.com/gomuks/gomuks/releases. gomuks web doesn't have releases yet, only CI binaries are available.

GitLab CI builds binaries for each commit: https://mau.dev/gomuks/gomuks/-/pipelines

The release and CI binaries for Linux are statically built and have no hard dependencies. The binaries for macOS require installing libolm, either with brew install libolm or by placing libolm.3.dylib from the CI in the same directory as the gomuks binary.

The gomuks backend requires having ffmpeg and ffprobe in $PATH to generate metadata when sending video files.

Direct links to latest CI binaries:

There are also community maintained packages for several distributions (gomuks legacy only). If you've made a new distro package, please add it to the list below.

Compiling from source

  1. Install Go 1.24 or higher.
    • Compiling the frontend for gomuks web also requires the latest LTS of Node.js or higher (currently v22).
    • libolm-dev must also be installed for end-to-end encryption.
  2. Clone the repo: git clone https://github.com/gomuks/gomuks.git && cd gomuks
    • To get legacy gomuks terminal, run git checkout master after cd.
  3. Build: ./build.sh (build.sh will simply call go build with some additional flags).

Simply pull changes (git pull) and run ./build.sh again to update.

Common compilation issues

  • fatal error: olm/olm.h: No such file or directory means you forgot to install libolm-dev, or that you installed it in a weird place which isn't in your default library lookup path.
    • In the latter case, set the LIBRARY_PATH and CPATH environment variables, e.g. export LIBRARY_PATH=/usr/local/lib CPATH=/usr/local/include.
  • fatal error: olm/pk.h: No such file or directory means you installed libolm2 instead of libolm3.
  • cgo: C compiler "gcc" not found: exec: "gcc": executable file not found in $PATH means you forgot to install C/C++ compilers.
  • //go:build comment without // +build comment means your Go version is slightly outdated.
  • cannot load embed: malformed module path "embed" or package embed is not in GOROOT means your Go version is very outdated.
  • cannot find package "maunium.net/go/gomuks/..." in any of: usually means your Go version is extremely outdated.

Docker (gomuks web)

The backend for gomuks web can also run in Docker. Docker images are available at dock.mau.dev/gomuks/gomuks.

On first run, gomuks will interactively ask for basic auth credentials, so you have to either run it with the -it flags, or create the config file yourself.

Keep in mind that the backend has all your encryption keys, which means it must be ran in a secure location.

FAQ

N.B. These only apply to gomuks legacy unless otherwise noted.

How do I verify the gomuks session?

To self-sign the device using your security key, use /cs fetch, enter your security key in the dialog that appears, then use /cs self-sign.

Alternatively, get your fingerprint and device ID from /fingerprint and pass them to the /verify command in an up-to-date Element Web or Desktop to do manual verification.

Why are old messages undecryptable?

gomuks currently doesn't support key backup and doesn't request keys automatically, so only messages sent after initial login will be decryptable. To see older messages, export keys to file from another client and use the /import command. After importing keys, you need to clear cache to have gomuks retry decrypting old messages.

How do I use a proxy?

Go's HTTP library reads the https_proxy environment variable by default (see https://pkg.go.dev/net/http#ProxyFromEnvironment for more info).

How do I copy text from gomuks?

Most terminals allow selecting text even when mouse mode is enabled by using shift+drag. However, that way doesn't work for copying multiline text, so you may prefer the /copy command for copying a single message, or Ctrl+L to enter plaintext mode where you can copy whatever you want.

Can I use gomuks with multiple accounts?

gomuks currently only supports one account at a time, but you can run multiple instances of gomuks with different data directories. See the entry below for details.

Debug logs

To get debug logs from gomuks, launch it with DEBUG=1 in the environment. Logs will be stored in ~/.local/state/gomuks by default. Prior to v0.3.1, the default path was /tmp/gomuks. The path can be changed using the DEBUG_DIR environment variable.

Where does gomuks store data?

By default, data is stored in the default config/cache/data directories using OS-specific conventions. To store all gomuks data in a custom directory, use the GOMUKS_ROOT environment variable.

You can also override individual directories using GOMUKS_THING_HOME (where THING is CONFIG, DATA or CACHE).

  • Config contains the main local config file.
  • Data contains encryption keys.
  • Cache contains things that can be refetched from the server: message history, room state, automatically downloaded files, preferences that are synced to the server, etc.

The default directory for manual file downloads (using the /download command) is the same on all systems: $GOMUKS_DOWNLOAD_HOME, $(xdg-user-dir DOWNLOAD), or $HOME/Downloads.

Note that the environment variables only take effect before first startup. After first startup, everything except the config path is saved to the config and will be read from there. To move existing gomuks data to a different path, you must change the paths in the config file.

Storage in gomuks web

The GOMUKS_* environment variables work mostly the same way as gomuks legacy, with a few exceptions:

  • There's no /download command and therefore no DOWNLOAD_HOME
  • Data also contains message history and other Matrix state, not only encryption keys (but media is still in cache).
  • Logs can be redirected using GOMUKS_LOG_HOME instead of DEBUG_DIR.
  • Environment variables are read on every startup, the paths aren't baked into the config file, except for the log path.

System-specific defaults

These are the base directories for each OS, data will be stored in the gomuks directory inside each base directory.

*nix

  • Config: $XDG_CONFIG_HOME or $HOME/.config
  • Cache: $XDG_CACHE_HOME or $HOME/.cache
  • Data: $XDG_DATA_HOME or $HOME/.local/share
  • Logs: $XDG_STATE_HOME or $HOME/.local/state

macOS

  • Config & Data: $HOME/Library/Application Support
  • Cache: $HOME/Library/Caches
  • Logs: $HOME/Library/Logs

Windows

  • Config & Data: %AppData%
  • Cache: %LocalAppData%
  • Logs: %LocalAppData%

Commands

Most gomuks web commands can be discovered using autocompletion, with the exception of a few special-cased commands: /plain, /me, /notice, /rainbow, /html and /unencrypted will work even though they don't show up in autocomplete.

The rest of this page only applies to gomuks legacy.

General

  • /help - View command list.
  • /quit - Close gomuks.
  • /clearcache - Clear room state and close gomuks.
  • /logout - Log out, clear caches and go back to the login view.
  • /fingerprint - Shows the Device ID and fingerprint, allowing verification of the session.
  • /copy [register] - Copy the selected message to the specified clipboard register (defaults to clipboard).
  • /toggle <thing> - Toggle user preferences.
    • rooms - Room list sidebar.
    • users - User list sidebar.
    • baremessages - Bare message mode where the sender name is inline with the messages.
    • images - Text image rendering.
    • typingnotif - Outgoing typing notifications.
    • emojis - :emoji: conversion when sending messages.
    • html - HTML input.
    • markdown - Markdown input.
    • downloads - Automatic downloads (this will also prevent images from working).
    • notifications - Desktop notifications.
    • unverified - Sending (e2ee keys for) messages to unverified devices. You need to restart gomuks for this setting to take effect.
    • inlineurls - Inline URLs in text. May not be supported in all terminals. You need to restart gomuks for this setting to take effect.

Media

Tab-completing file paths is supported in all these commands.

  • /download [path] - Downloads file from selected message. If path is not specified, it defaults to <download_dir>/<message.body>. download_dir defaults to $HOME/Downloads.
  • /open [path] - Download file from selected message and open it with xdg-open. If path is not specified, the file will be downloaded to the media cache.
  • /upload <path> - Upload the file at the given path to the current room. Note that to include audio/video file metadata (dimensions and duration), you must have ffprobe installed.

Sending special messages

  • /me <text> - Send an emote.
  • /notice <text> - Send a notice (generally used for bot messages).
  • /rainbow <text> - Send rainbow text.
  • /rainbowme <text> - Send rainbow text in an emote.
  • /rainbownotice <text> - Send rainbow text in a m.notice message.
  • /reply [text] - Reply to the selected message. If text is not specified, the next message will be used.
  • /react <reaction> - React to the selected message.
  • /redact [reason] - Redact (delete) the selected message.
  • /edit - Edit the selected message.

Encryption

These commands support tab-completing file paths and user/device IDs using the displaynames of users/devices.

Accepting incoming interactive verification requests is not yet supported, only outgoing requests via /verify work.

  • /fingerprint - View the fingerprint of your device (for legacy/non-interactive verification).
  • /devices <user id> - View the device list of a user.
  • /device <user id> <device id> - Show info about a specific device.
  • /unverify <user id> <device id> - Un-verify a device.
  • /blacklist <user id> <device id> - Blacklist a device. Message keys are never sent to blacklisted devices.
  • /verify <user id> <device id> [fingerprint] - Verify a device. If the fingerprint is not provided, interactive emoji verification will be started.
  • /export <path> - Export all message decryption keys to the given path.
  • /export-room <path> - Export message decryption keys for the current room to the given path.
  • /import <path> - Import message decryption keys from the given path.
  • /cross-signing <subcommand> [...] - Cross-signing commands. Somewhat experimental. (alias: /cs).
    • status - Check the status of your own cross-signing keys.
    • generate [--force] - Generate and upload new cross-signing keys. This will prompt you to enter your account password. If you already have existing keys, --force is required.
    • self-sign - Sign the current device with cached cross-signing keys. (or in other words, verify the current device).
    • fetch [--save-to-disk] - Fetch your cross-signing keys from SSSS and decrypt them. If --save-to-disk is specified, the keys are saved to disk.
    • upload - Upload your cross-signing keys to SSSS.
  • /ssss <subcommand> [...] - Secure Secret Storage (and Sharing) commands. Very experimental.
    • status [key ID] - Check the status of your SSSS.
    • generate [--set-default] - Generate a SSSS key and optionally set it as the default.
    • set-default <key ID> - Set a SSSS key as the default.

Rooms

Creating

  • /pm <user id> [...] - Start a private chat with the given user(s).
  • /create [room name] - Create a new room.

Joining

  • /join <room> [server] - Join the room with the given room ID or alias, optionally through the given server.
  • /accept (in a room you're invited to) - Accept the invite.
  • /reject (in a room you're invited to) - Reject the invite.

Existing

  • /invite <user id> - Invite the given user ID to the room.
  • /roomnick <name> - Change your per-room displayname.
  • /tag <tag> <priority> - Add the room to <tag>. <tag> should start with u. and <priority> should be a float between 0 and 1. Rooms are sorted in ascending priority order.
  • /untag <tag> - Remove the room from <tag>.
  • /tags - List the tags the room is in.
  • /powerlevel [thing] [level] - View or change power levels in rooms.

Leaving

  • /leave - Leave the current room.
  • /kick <user id> [reason] - Kick a user.
  • /ban <user id> [reason] - Ban a user.
  • /unban <user id> - Unban a user.

Aliases

  • /alias add <localpart> - Add #<localpart>:your.server as an address for the current room.
  • /alias remove <localpart> - Remove #<localpart>:your.server (can be ran in any room).
  • /alias resolve <alias> - Resolve <alias> or #<alias>:your.server and reply with the room ID.

Raw events

  • /send <room id> <event type> <content> - Send a custom event.
  • /setstate <room id> <event type> <state key/-> <content> - Change room state.
  • /msend <event type> <content> - Send a custom event to the current room.
  • /msetstate <event type> <state key/-> <content> - Change room state in the current room.
  • /id - Get the current room ID.

Debugging

  • /hprof - Create a heap profile and write it to gomuks.heap.prof in the current directory.
  • /cprof <seconds> - Profile the CPU usage for the given number of seconds and write it to gomuks.cpu.prof.
  • /trace <seconds> - Trace calls for the given number of seconds and write traces to gomuks.trace.

Shortcuts

This page only applies to gomuks legacy.

Keyboard

Ctrl and Alt are interchangeable in most keybindings, but the other one may not work depending on your terminal emulator.

  • Switch rooms: Ctrl + ↑, Ctrl + ↓
  • Scroll chat (page): PgUp, PgDown
  • Jump to room: Ctrl + K, type part of a room's name, then Tab and Enter to navigate and select room
  • Plaintext mode: Ctrl + L
  • Newline: Alt + Enter
  • Autocompletion: Tab (emojis, usernames, room aliases and commands)

Editing messages

↑ and ↓ can be used at the start and end of the input area to jump to edit the previous or next message respectively.

Selecting messages

After using commands that require selecting messages (e.g. /reply and /redact), you can move the selection with ↑ and ↓ confirm with Enter.

Mouse

  • Click to select message (for commands such as /reply that act on a message)
  • Ctrl + click on image to open in your default image viewer (xdg-open)
  • Click on a username to insert a mention of that user into the composer

Customizing keybindings

This page only applies to gomuks legacy.

Keybindings can be customized to some extent by creating a file called keybindings.yaml in the config directory (see the FAQ for the location of the config directory).

The file should have the same format as the default keybindings.yaml file, but you only need to specify the bindings you want to override.

For example, to use enter for newline, you'd want something like this. Note that terminals can't detect shift+enter, and usually only either ctrl or alt works.

main:
  'Enter': add_newline
  'Ctrl+Enter': unbind
  'Alt+Enter': unbind

room:
  'Enter': unbind
  'Ctrl+Enter': send
  'Alt+Enter': send

Debugging

This page only applies to gomuks legacy.

If something doesn't work but it doesn't crash, check the /tmp/gomuks/debug.log file for any errors. You can override the location of this file with the DEBUG_DIR environment variable.

Developing

Set DEBUG=1 to enable partial deadlock detection and to write panics to stdout instead of a file.

To build and run with race detection, use go install -race and set GORACE='history_size=7 log_path=/tmp/gomuks/race.log' when starting gomuks, then check /tmp/gomuks/race.log.<pid>. Note that race detection will use a lot of extra resources.

Proper debuggers are too fancy, but normal prints won't work in a TUI application. To write to the debug log mentioned previously, use the maunium.net/go/gomuks/debug package:

package foo

import (
	"maunium.net/go/gomuks/debug"
)

func Foo() {
	debug.Print("WHY ISN'T IT WORKING?!?!?")
	debug.PrintStack()
}

RPC API

Envelope

All RPC messages (requests, responses and events) use the same envelope format:

  • command (string): the command/event name.
  • request_id (integer): incrementing (or decrementing) message ID. Responses will always contain the same ID. Requests without an ID will never be replied to. For events, the backend will start at -1 and go backwards.
  • data (any): payload for the command/event, type depends on the command.

Responses

For every request with request_id set, the backend replies exactly once with the same request_id and one of:

  • command: "response" with data containing the command-specific return value.
  • command: "error" with data being the error message string.

Cancellation

Requests can be canceled by sending a cancel request with the target request_id inside data, plus an optional reason string. Cancellation is best-effort: some operations may not stop immediately and there is no guarantee of rollbacks.

Websocket

The main method of connecting is using the websocket. The websocket is at _gomuks/websocket and requires standard cookie authentication.

However, the RPC API is intentionally just JSON, so it can be sent over other transports as well. In particular, when bundling the backend with the frontend, it is recommended to use a direct in-process channel rather than the websocket.

Compression

If the compress query param is set to 1, the websocket will use a connection-wide deflate compression similar to how Discord's gateway works. Only messages sent by the backend are compressed; client messages are not.

Enabling compression will also enable batched messages in a single frame, i.e. multiple JSON objects may be concatenated together using a newline (\n) as the separator if the backend detects that the connection isn't keeping up. There is currently no option to turn off batching when compression is enabled.

Compression is recommended for lower bandwidth networks like mobile data. It can save up to 70% of bandwidth. The primary downside is that standard developer tools will no longer understand the websocket messages.

Event buffering

The backend will buffer events that the client hasn't acknowledged yet to allow faster resuming in case the websocket is interrupted. To use session resumption, the client has to handle the run_id command and store the run_id field inside the data. When reconnecting, the client should include the run ID as well as the most recent negative request ID it received in the run_id and last_received_event query params respectively.

The event buffer is entirely in-memory, which means resumption will fail if the backend has been restarted. For non-resumed inits, the first sync_complete event will have the clear_state flag set to true. For successful resumes, the client will only get missed events rather than the full initial sync.

The init_complete event is always sent once the client is caught up regardless of whether the resume succeeded or not.

Keepalive pings and event acknowledgement

Clients MUST send periodic pings to keep the connection alive. The backend will kill connections that don't send any data for over 60 seconds. Clients SHOULD implement similar timeouts and reconnect if they don't receive any data from the backend. The recommended ping interval is 15 seconds.

Unlike normal requests, pings are exclusive to the websocket layer and will result in "command": "pong" instead of "command": "response".

In addition to keeping the connection open, pings are used to acknowledge received events so that the backend can remove them from its in-memory cache. Clients should include the most recent negative request ID they received in the last_received_id field inside the data of the ping.

Example

Request:

{
  "command": "ping",
  "request_id": 123,
  "data": {
    "last_received_id": -456
  }
}

Response:

{
  "command": "pong",
  "request_id": 123
}

Type notes

  • room_id, event_id, user_id, etc are Matrix IDs (strings) in JSON.
  • Many responses reference gomuks DB types (e.g. database.Event). Treat them as JSON objects; structure is defined by gomuks’ API and may evolve.
  • Some request fields are raw JSON blobs (e.g. content) that must match the Matrix spec for the given event type.

Commands

get_state

Get current client state (login/verification/session info). Note that state is also emitted as client_state events, so you usually don't need to request it manually.

  • Request data: N/A
  • Response data: ClientState
    • is_initialized (bool)
    • is_logged_in (bool)
    • is_verified (bool)
    • user_id (string, optional)
    • device_id (string, optional)
    • homeserver_url (string, optional)

cancel

Cancel an in-flight request.

  • Request data:
    • request_id (int, required): request ID to cancel.
    • reason (string): optional cancellation reason.
  • Response data: bool
    • true if a request with that ID was found and cancellation was triggered.
    • false if no in-flight request with that ID exists.

send_message

Send a Matrix message into a room. This is a higher-level helper around sending m.room.message (and related) content. This will always perform an asynchronous send, which means the returned event won't have an ID yet. Listen for the send_complete event to get the final result.

  • Request data:
    • room_id (string, required)
    • base_content (object): non-text m.room.message event content. Only standard fields in mautrix-go's MessageEventContent are allowed here. This should be used for things like media attachments, as well as MSC4332 bot commands.
    • extra (object): non-standard fields for content.
    • text (string): text to send. If set, this will be used to fill the message body, formatted_body, format and msgtype fields. Media captions should be put here even when using base_content for the rest of the media.
    • relates_to (object): Standard m.relates_to data.
    • mentions (object): Standard m.mentions data.
    • url_previews (array): Beeper link preview objects (MSC4095).
  • Response data: database.Event

send_event

Send an arbitrary event into a room.

  • Request data:
    • room_id (string, required)
    • type (string, required)
    • content (object, required)
    • disable_encryption (bool): if true, don’t encrypt the event even if the room is encrypted.
    • synchronous (bool): if true, perform sending synchronously (returned DB event will have the event ID set, unless the send fails).
  • Response data: database.Event

resend_event

Retry sending a previously failed outgoing event.

  • Request data:
    • transaction_id (string, required)
  • Response data: database.Event

report_event

Report an event to the homeserver.

  • Request data:
    • room_id (string, required)
    • event_id (string, required)
    • reason (string)
  • Response data: N/A

redact_event

Redact an event.

  • Request data:
    • room_id (string, required)
    • event_id (string, required)
    • reason (string)
  • Response data: mautrix.RespSendEvent

set_state

Send a state event into a room.

  • Request data:
    • room_id (string, required)
    • type (string, required)
    • state_key (string)
    • content (object, required)
    • delay_ms (int): optional unstable delayed-event send (milliseconds).
  • Response data: event_id (string)

update_delayed_event

Update or cancel an unstable delayed event (MSC4140/unstable delay API).

set_membership

Invite, kick, ban or unban a user.

  • Request data:
    • action (string, required): one of invite, kick, ban, unban.
    • room_id (string, required)
    • user_id (string, required)
    • reason (string)
    • msc4293_redact_events (bool): if true, the ban event will set a flag to suggest that clients hide all the user's messages.
  • Response data: empty object

set_account_data

Set global or per-room account data.

  • Request data:
    • room_id (string): omit to set global account data.
    • type (string, required)
    • content (object, required)
  • Response data: N/A

mark_read

Send a read receipt / mark room as read.

  • Request data:
    • room_id (string, required)
    • event_id (string, required)
    • receipt_type (string, required): Matrix receipt type (e.g. m.read).
  • Response data: N/A

set_typing

Set typing notification state.

  • Request data:
    • room_id (string, required)
    • timeout (int): typing timeout in milliseconds. Set to 0 to stop typing.
  • Response data: N/A

get_profile

Fetch a Matrix user profile.

  • Request data:
    • user_id (string, required)
  • Response data: The raw profile data of the user.

set_profile_field

Set one profile field for the current user.

  • Request data:
    • field (string, required)
    • value (any, required)
  • Response data: N/A

get_mutual_rooms

Get rooms shared with a user.

  • Request data:
    • user_id (string, required)
  • Response data: string[] (array of room IDs)

track_user_devices

Start tracking a user’s devices if they're not already tracked, then return encryption info (same result as get_profile_encryption_info).

get_profile_encryption_info

Get the device list and trust state information for a user.

  • Request data:
    • user_id (string, required)
  • Response data: ProfileEncryptionInfo
    • devices_tracked (bool)
    • devices (array of ProfileDevice)
      • device_id (string)
      • name (string)
      • identity_key (string)
      • signing_key (string)
      • fingerprint (string)
      • trust_state (string)
    • master_key (string)
    • first_master_key (string)
    • user_trusted (bool)
    • errors (string[])

get_event

Fetch an event from a room.

  • Request data:
    • room_id (string, required)
    • event_id (string, required)
    • unredact (bool): if true, fetch an unredacted copy when possible.
  • Response data: database.Event

Get events related to a given event (e.g. reactions, edits, replies depending on relation type).

  • Request data:
    • room_id (string, required)
    • event_id (string, required)
    • relation_type (string, required)
  • Response data: database.Event[] (array of events)

get_event_context

Fetch context around an event (before/after timeline slices) from the homeserver. This is used for jumping to a specific point on the timeline. Note that there is currently no safe way to merge back into the main timeline, so jumping has to be implemented as a separate view.

  • Request data:
    • room_id (string, required)
    • event_id (string, required)
    • limit (int)
  • Response data: https://pkg.go.dev/go.mau.fi/gomuks/pkg/hicli/jsoncmd#EventContextResponse
    • start (string)
    • end (string)
    • before (database.Event[])
    • after (database.Event[])
    • event (database.Event)

paginate_manual

Manually paginate messages from the homeserver using a pagination token. This is used to paginate after jumping to a specific event using get_event_context and for normal pagination in the thread view.

  • Request data:
    • room_id (string, required)
    • thread_root (string): root event ID for thread pagination.
    • since (string): next_batch token from previous request or the start/end fields of get_event_context.
    • direction (string): b or f.
    • limit (int)
  • Response data: ManualPaginationResponse
    • events (database.Event[])
    • next_batch (string)

get_room_state

Get room state, optionally after fetching it from the homeserver.

  • Request data:
    • room_id (string, required)
    • refetch (bool): force refetch the entire state from the homeserver.
    • fetch_members (bool): fetch membership events from homeserver. The client should always set this when opening a room if has_member_list is false in the room metadata.
    • include_members (bool): whether to include the member list in the response. This can be used with fetch_members to tell the backend to fetch the list in the background rather than waiting for it.
  • Response data: database.Event[] (array of state events)

get_specific_room_state

Get specific state events by database GUID keys.

  • Request data:
    • keys (array, required): array of database.RoomStateGUID.
      • room_id (string, required)
      • type (string, required)
      • state_key (string)
  • Response data: database.Event[] (array of state events)

get_receipts

Get cached read receipts for a set of event IDs.

  • Request data:
    • room_id (string, required)
    • event_ids (string[], required)
  • Response data: map event_id → Receipt[]

AI SLOP HAS BEEN REVIEWED UP TO HERE

paginate

Paginate locally stored timeline history.

  • Request data:
    • room_id (string)
    • max_timeline_id (number): maximum timeline row ID to start from.
    • limit (int)
    • reset (bool): reset pagination state.
  • Response data: PaginationResponse

PaginationResponse:

  • events (database.Event[])
  • receipts (map event_id → Receipt[])
  • related_events (database.Event[])
  • has_more (bool)
  • from_server (bool)

get_room_summary

Fetch a room summary (typically for room previews).

  • Request data:
    • room_id_or_alias (string)
    • via (string[], optional)
    • reason (string, optional)
  • Response data: mautrix.RespRoomSummary

get_space_hierarchy

Fetch a space hierarchy.

  • Request data:
    • room_id (string)
    • from (string)
    • limit (int)
    • max_depth (int|null)
    • suggested_only (bool)
  • Response data: mautrix.RespHierarchy

join_room

Join a room by room ID or alias.

  • Request data:
    • room_id_or_alias (string)
    • via (string[])
    • reason (string)
  • Response data: mautrix.RespJoinRoom

knock_room

Knock on a room by room ID or alias.

  • Request data:
    • room_id_or_alias (string)
    • via (string[])
    • reason (string)
  • Response data: mautrix.RespKnockRoom

leave_room

Leave a room.

  • Request data:
    • room_id (string)
    • reason (string)
  • Response data: mautrix.RespLeaveRoom

Note: leaving may also clear local invite state even for certain “already left” errors.

create_room

Create a new room.

  • Request data: mautrix.ReqCreateRoom (Matrix create-room JSON).
  • Response data: mautrix.RespCreateRoom

mute_room

Mute or unmute a room by manipulating push rules.

  • Request data:
    • room_id (string)
    • muted (bool)
  • Response data: bool

Note: the current implementation returns true when muting succeeds and false when unmuting succeeds.

ensure_group_session_shared

Ensure the encryption group session for a room has been shared to devices.

  • Request data:
    • room_id (string)
  • Response data: bool (always true on success)

send_to_device

Send a to-device event.

  • Request data:
    • event_type (string): Matrix to-device event type.
    • messages (object): from mautrix.ReqSendToDevice (map of user→device→content).
    • encrypted (bool): whether the provided payload is already encrypted.

(Other mautrix.ReqSendToDevice fields may also be accepted.)

  • Response data: mautrix.RespSendToDevice

resolve_alias

Resolve a room alias.

  • Request data:
    • alias (string)
  • Response data: mautrix.RespAliasResolve

request_openid_token

Request an OpenID token from the homeserver.

  • Request data: {}
  • Response data: mautrix.RespOpenIDToken

logout

Log out the current session (if supported by the embedding).

  • Request data: {}
  • Response data: bool (always true on success)

login

Log in using a homeserver URL, username, and password.

  • Request data:
    • homeserver_url (string)
    • username (string)
    • password (string)
  • Response data: bool (always true on success)

login_custom

Log in using a fully custom Matrix login request object.

  • Request data:
    • homeserver_url (string)
    • request (object): mautrix.ReqLogin JSON.
  • Response data: bool (always true on success)

verify

Verify the session using a recovery key.

  • Request data:
    • recovery_key (string)
  • Response data: bool (always true on success)

discover_homeserver

Discover homeserver URL using .well-known based on a Matrix user ID.

  • Request data:
    • user_id (string)
  • Response data: mautrix.ClientWellKnown

get_login_flows

Fetch supported login flows from a homeserver URL.

  • Request data:
    • homeserver_url (string)
  • Response data: mautrix.RespLoginFlows

register_push

Register (store) push configuration in gomuks’ local database.

  • Request data: database.PushRegistration
  • Response data: bool (always true on success)

listen_to_device

Enable or disable including to-device messages in sync data.

  • Request data: bool
  • Response data: bool (previous value before this request)

get_turn_servers

Fetch TURN server configuration.

  • Request data: {}
  • Response data: TURN server response from mautrix (/voip/turnServer).

get_media_config

Fetch media repository configuration.

  • Request data: {}
  • Response data: media config response from mautrix (/config).

calculate_room_id

Calculate a room ID locally from a timestamp and creation content.

  • Request data:
    • timestamp (int64)
    • content (object): room creation content JSON.
  • Response data: room_id (string)

Events (backend → client)

Events are messages sent by the backend when new data is available. The request IDs will always be negative. The client MUST NOT respond to events.

sync_complete

A sync batch has been fully processed and stored. This is also used for sending the room list to the client when first connecting.

  • Event data: SyncComplete
    • since (string)
    • clear_state (bool)
    • account_data (map)
    • rooms (map room_id → SyncRoom)
    • left_rooms (string[])
    • invited_rooms (array)
    • space_edges (map)
    • top_level_spaces (string[])
    • to_device (array)

sync_status

Sync status update.

  • Event data:
    • type (string, required): ok, waiting, erroring, permanently-failed
    • error (string)
    • error_count (int)
    • last_sync (number, unix milliseconds)

events_decrypted

One or more events were decrypted after initially failing to decrypt.

  • Event data:
    • room_id (string, required)
    • preview_event_rowid (number): If the preview event of the room changed, the new rowid to preview.
    • events (database.Event[], required)

typing

Typing notifications for a room.

  • Event data:
    • room_id (string)
    • user_ids (string[])

send_complete

A previously started send finished (success or failure).

  • Event data:
    • event (database.Event)
    • error (string|null)

client_state

Client state changed.

  • Event data: ClientState (same as get_state response)

image_auth_token (websocket only)

Authentication token for image/media requests. The token is valid for an hour and a new one is sent every 30 minutes.

  • Event data: string

init_complete

Emitted after client initialization completes (either after initial sync or after catching up on resume).

  • Event data: {}

run_id

Metadata about the currently running backend process.

  • Event data:
    • run_id (string): The run ID to use for resuming connections (event buffering is in-memory, so connections can't be resumed across backend restarts).
    • etag (string): Used by the frontend to force reload if it detects it's an outdated cached copy.
    • vapid_key (string): VAPID public key for web push subscriptions.

HTTP API

_gomuks/auth is used to acquire or refresh cookies. If an existing gomuks_auth cookie is provided, it's validity is extended. Otherwise, basic auth credentials will be checked.

Available query parameters:

  • output - can be json (JSON in response body) or omitted (Set-Cookie header)
  • no_prompt - if set to true, the WWW-Authenticate header will not be set when credentials are missing or invalid.
  • insecure_cookie - if set to true, the cookie will not have the Secure flag set.

TODO other endpoints