Introduction

Welcome to the gomuks docs!

Discussion

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.

An Electron wrapper is also available, which includes the backend. The setup steps below can be ignored when using the desktop app. Just install the app and open it.

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.

Setup steps

Acquire a binary using the instructions below (either installing a package or compiling from source)
Run the binary. It'll prompt you to create basic auth credentials on the first run. They're not your Matrix credentials.
Open the web interface (at http://localhost:29325 by default)

If you want to have gomuks behind a reverse proxy, you'll need to adjust listen_address and origin_patterns in the config file.

Installing a package

Prebuilt binaries can be found in GitHub releases or GitLab CI where every commit is built.

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:

gomuks backend (includes web frontend): linux/amd64, linux/arm64, linux/arm, macos/arm64, windows/amd64
gomuks terminal (frontend only): linux/amd64, linux/arm64, linux/arm, macos/arm64
gomuks android (currently frontend wrapper only): arm64-v8a.apk, x86_64.apk
gomuks desktop: debian/amd64, debian/arm64, macos/arm64, windows/amd64

Compiling from source

Install Go 1.25 or higher.
- Compiling the frontend for gomuks web also requires the latest LTS of Node.js or higher (currently v24).
- libolm-dev must also be installed for end-to-end encryption, unless you opt to use goolm.
Clone the repo: git clone https://github.com/gomuks/gomuks.git && cd gomuks
Build: ./build.sh (build.sh will simply call go build with some additional flags).
- To add custom build tags, such as goolm, set them in the GO_BUILD_TAGS environment variable, which the build script will read.

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

To build the terminal frontend, use ./build-terminal.sh. The backend and terminal frontend are separate binaries for now.

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.
- Alternatively, build with goolm to avoid the libolm dependency entirely.
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

Can I connect to a remote gomuks backend?

Yes, the recommended way to do it is to run the backend behind a reverse proxy (see entry below). It is possible to connect directly without a reverse proxy, but LANs are dangerous, so using TLS is recommended, which requires a reverse proxy.

If you really don't want to use TLS, you'll have to set insecure_cookies in the config to allow connecting from an insecure context. By default, the auth cookie will only work on localhost and https sites.

listen_address and origin_patterns have to be changed to allow connecting from non-localhost addresses.

Can I run the backend behind a reverse proxy?

Yes, origin_patterns just needs to be changed to match what the client will use to connect to. listen_address may also need to be changed if using something like Docker where the reverse proxy can't connect using localhost.

If you want to use custom auth instead of the standard basic auth, you can either have your reverse proxy inject it, or use the secret config option to disable auth entirely in the backend. When disabling auth, you need to be extra careful not to allow untrusted requests to the backend.

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.

If you aren't using a reverse proxy, you'll have to use different ports and localhosts to access the gomukses to avoid cookie conflicts. The port can be changed in the config. All modern browsers should force anything.localhost to connect to localhost, so you could use http://main.localhost:8000 and http://anotheraccount.localhost:8001 for example.

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 config file with things like listen address, basic auth credentials and log config.
Data contains all persistent data (messages, encryption keys, etc). Deleting the data directory will log you out.
Cache contains media and can be safely deleted at any time. The cache is content-addressed, so it can also be shared between multiple gomuks instances.

GOMUKS_LOGS_HOME can also be used to redirect logs, but the variable is only read on first startup and then baked into the config file.

Electron wrapper

The Electron gomuks desktop stores backend data under the default Electron session data directory, which means ~/.config/gomuks-desktop on Linux and ~/Library/Application Support/gomuks-desktop on macOS.

The config for the Electron side is in gomuks-desktop.json, which is where backends are defined. All backend entries must have type (embedded or remote) and a unique name. Remote backends must also have address and optionally username and password. All backends can have displayname to use in the account picker.

Each embedded backend has its own subdirectory named after the name field in the config. The media cache is shared by all backends and will be in the gomuks-cache subdirectory.