Matron Desktop is a Matrix client for desktop platforms with Matron Web at its core. It is a fork of Element Desktop.
Before you do anything else, fetch the dependencies:
pnpm install
Since this package is just the Electron wrapper for Matron Web, it doesn't contain any of the Matron Web code, so the first step is to get a working copy of Matron Web. There are a few ways of doing this:
# Fetch the prebuilt release package from the matron-web GitHub releases page. The version
# fetched will be the same as the local matron-desktop package.
# We're explicitly asking for no config, so the packaged app will have no config.json.
pnpm run fetch --noverify --cfgdir ""
...or if you'd like to use GPG to verify the downloaded package:
# Fetch the public key from the web server over a secure connection and import
# it into your local GPG keychain (you'll need GPG installed). You only need to to do this
# once.
pnpm run fetch --importkey
# Fetch the package and verify the signature
pnpm run fetch --cfgdir ""
...or either of the above, but fetching a specific version:
# Fetch the prebuilt release package from the matron-web GitHub releases page. The version
# fetched will be the same as the local matron-desktop package.
pnpm run fetch --noverify --cfgdir "" v1.5.6
If you only want to run the app locally and don't need to build packages, you can
provide the webapp directory directly:
# Assuming you've checked out and built a copy of matron-web in ../matron-web.
# Note that you will not be able to `pnpm build` after this, but `pnpm start`
# will work fine.
ln -s ../matron-web/webapp ./
[TODO: add support for fetching develop builds, arbitrary URLs and arbitrary paths]
TODO: List native pre-requisites
Optionally, build the native modules, which include support for searching in encrypted rooms and secure storage. Skipping this step is fine, you just won't have those features.
Then, run
pnpm run build
This will do a couple of things:
- Run the
setversionscript to set the local package version to match whatever version of Matron Web you installed above. - Run electron-builder to build a package. The package built will match the operating system you're running the build process on.
Alternatively, you can also build using docker, which will always produce the linux package:
# Run this once to make the docker image
pnpm run docker:setup
pnpm run docker:install
# if you want to build the native modules (this will take a while)
pnpm run docker:build:native
pnpm run docker:build
After running, the packages should be in dist/.
If you'd just like to run the electron app locally for development:
pnpm start
If you'd like the packaged Matron to have a configuration file, you can create a
config directory and place config.json in there, then specify this directory
with the --cfgdir option to pnpm run fetch, eg:
mkdir myconfig
cp /path/to/my/config.json myconfig/
pnpm run fetch --cfgdir myconfig
The config dir for the official Matron app is in matron/. If you use this,
your app will auto-update itself using builds from the official distribution.
To run multiple instances of the desktop app for different accounts, you can
launch the executable with the --profile argument followed by a unique
identifier, e.g matron-desktop --profile Work for it to run a separate profile and
not interfere with the default one.
Alternatively, a custom location for the profile data can be specified using the
--profile-dir flag followed by the desired path.
%APPDATA%\$NAME\config.jsonon Windows$XDG_CONFIG_HOME/$NAME/config.jsonor~/.config/$NAME/config.jsonon Linux~/Library/Application Support/$NAME/config.jsonon macOS
In the paths above, $NAME is typically Matron, unless you use --profile $PROFILE in which case it becomes Matron-$PROFILE, or it is using one of
the above created by a pre-1.7 install, in which case it will be Riot or
Riot-$PROFILE.
You may also specify a different path entirely for the config.json file by
providing the --config $YOUR_CONFIG_JSON_FILE to the process, or via the
MATRON_DESKTOP_CONFIG_JSON environment variable.
To add a new translation, head to the translating doc.
For a developer guide, see the translating dev doc.
If you run into any bugs or have feedback you'd like to share, please let us know on GitHub.
To help avoid duplicate issues, please view existing issues first (and add a +1) or create a new issue if you can't find it. Please note that this issue tracker is associated with the matron-web repo, but is also applied to the code in this repo as well.
Copyright (c) 2016-2017 OpenMarket Ltd
Copyright (c) 2017 Vector Creations Ltd
Copyright (c) 2017-2025 Matron Contributors
This software is multi licensed. It can be used either:
(1) for free under the terms of the GNU Affero General Public License (as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version); OR
(2) for free under the terms of the GNU General Public License (as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version); OR
(3) under other licensing terms as agreed upon by the contributors. Unless required by applicable law or agreed to in writing, software distributed under the Licenses is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the Licenses for the specific language governing permissions and limitations under the Licenses.