Deploying the desktop app

How to install the Antimatter desktop app on the computers of a company or school, and set its servers, the username and the update checks centrally on Windows, macOS and Linux.

Download the app

The desktop app's releases are on GitHub, at github.com/AntimatterChat/desktop-app/releases. Like the server, the app is in beta: a release whose version has a suffix after a hyphen is marked Pre-release. Each release has a SHA256SUMS file with the checksum of every file. Check a download with sha256sum --check --ignore-missing SHA256SUMS on Linux, or compare the output of Get-FileHash <file> -Algorithm SHA256 in PowerShell with its line in SHA256SUMS.

Windows (x64 and arm64): the .exe installer, the .msi package, or a .zip archive. For example antimatter-desktop-<version>-win-x64.exe and antimatter-desktop-<version>-win-x64.msi.
macOS: a .dmg disk image or a .zip, for Apple silicon (arm64), Intel Macs (x64) or both (universal).
Linux (x64 and arm64): a .deb or .rpm package, an AppImage, a Flatpak bundle or a .tar.gz archive.

Which Windows installer to use

	The .exe installer	The .msi package
For	People who install the app themselves	Companies that deploy it to their computers
Installs	For the current Windows account only, in `%LOCALAPPDATA%\Programs\antimatter-desktop`, without administrator rights	For every user of the computer, in `C:\Program Files\Antimatter`, with administrator rights
Updates	The app checks for new versions and offers to download the new `.exe`, which updates the installed copy in place	The app doesn't check for new versions: you deploy them

The app checks for new versions on GitHub, every hour while it runs, and only sees full releases, not prereleases. When it finds one, it tells the person and offers a link to download it. A copy installed with the MSI doesn't check by default, because the people who use it usually can't install software. You can turn the checks on for it with the EnableAutoUpdater setting: the download it offers is then the new .msi, which needs administrator rights.

Use the MSI for a managed deployment with SCCM (Configuration Manager), Intune or Group Policy software installation. Installing the MSI removes the .exe copy of the account running the installation, if there is one.

The settings you can manage

The same settings exist on every system. On Windows they are registry values under SOFTWARE\Policies\Antimatter, in HKEY_LOCAL_MACHINE (for the computer) or HKEY_CURRENT_USER (for one user). On macOS and Linux they are keys of the managed preferences or of the policy file.

Setting	On Windows	On macOS and Linux	What it does
`DefaultServerList`	A subkey with one string value per server: the value name is the name of its tab, the data is its URL	An array of dictionaries (objects on Linux) with `name` and `url`	Adds servers to the app. People can't edit or remove them.
`DefaultUsername`	A string	A string	Fills in the username on the login page of these servers.
`EnableServerManagement`	A DWORD, 0 or 1	A boolean	0 or `false`: people can only use the servers set by `DefaultServerList`, and the app hides the options to add, edit and remove servers. Not set: people can add their own servers.
`EnableAutoUpdater`	A DWORD, 0 or 1	A boolean	0 or `false`: the app never checks for new versions, and hides Check for Updates. 1 or `true`: it checks, even when installed with the MSI. Not set: the `.exe` copy checks, the MSI copy doesn't.
`TrustedEmbeddedMediaOrigins`	A subkey with string values, each a JSON object with `serverOrigin` and `embeddedOrigin`	An array of dictionaries with `serverOrigin` and `embeddedOrigin`	Lets content embedded in a server's pages, such as a video meeting page, use the camera and microphone permissions granted to that server.

The username is only filled in on the login page of the servers set by policy, never on a server a person added, and never over what someone typed. People can still change it. Environment variables between percent signs are replaced, so one value fits everyone: %USERNAME% on Windows or %USER% on macOS and Linux gives the account name, and %USERNAME%@example.com an email address that follows this pattern. If a variable isn't set, the app fills in nothing.
If you turn server management off, set at least one server in DefaultServerList.
On Windows, a computer policy (HKEY_LOCAL_MACHINE) wins over a user policy (HKEY_CURRENT_USER). The server lists of both are combined.
The app reads the settings when it starts: after a change, people must quit and reopen it.

Windows: silent installation with the MSI

The MSI takes public properties that write the settings as computer policies, in HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Antimatter. Use them in an SCCM application, an Intune app or a script. In PowerShell:

msiexec /i antimatter-desktop-<version>-win-x64.msi /qn SERVERURL=https://chat.example.com SERVERNAME=Chat DEFAULTUSERNAME='%USERNAME%' AUTOUPDATE=0 SERVERMANAGEMENT=0

Property	Writes	If not given
`SERVERURL`	A server in `DefaultServerList`, with this URL	No server
`SERVERNAME`	The name of that server's tab	`Antimatter`
`DEFAULTUSERNAME`	`DefaultUsername`	Nothing
`AUTOUPDATE`	`EnableAutoUpdater`, 0 or 1	Nothing: the MSI copy doesn't check for updates
`SERVERMANAGEMENT`	`EnableServerManagement`, 0 or 1	Nothing: people can add servers

A property that isn't given writes nothing, so it doesn't overwrite a value set by Group Policy. AUTOUPDATE and SERVERMANAGEMENT only accept 0 or 1. The MSI sets one server: use Group Policy for more.
DEFAULTUSERNAME must reach the installer as the text %USERNAME%, so that the app replaces it for each person. Otherwise the shell running the installation replaces it with its own account name. In PowerShell, keep the single quotes. In a .bat file, write %%USERNAME%%. After a test installation, check in the registry that DefaultUsername holds %USERNAME%.
Pass the properties again at every upgrade. Installing a new version of the MSI removes the old one, with the values it wrote, then writes the values of the new command line. SCCM and Intune keep the command line of an application: reuse it for each new version. Or set the policies with Group Policy or Intune instead, which upgrades don't touch.
The MSI and Group Policy write the same registry values. For each setting, use one or the other: uninstalling the MSI deletes the values it wrote, even if Group Policy set them too.
The MSI also records its installation folder in HKEY_LOCAL_MACHINE\SOFTWARE\Antimatter\Desktop (InstallDir). This is how the app knows it was installed with the MSI.

To uninstall: msiexec /x antimatter-desktop-<version>-win-x64.msi /qn. In Intune, the "Windows app (Win32)" type takes the same command lines. For the "Line-of-business app" type, add the properties to its command-line arguments.

Windows: Group Policy and Intune

The administrative templates, antimatter.admx and en-US\antimatter.adml, are in the gpo folder of the installed app (C:\Program Files\Antimatter\gpo for the MSI), and in the resources/windows/gpo folder of the app's repository. They show these policies, under Administrative Templates › Antimatter:

Policy	Registry value	Configuration
Servers (DefaultServerList)	`DefaultServerList` subkey	computer and user
Username to prefill (DefaultUsername)	`DefaultUsername`	computer and user
Let people add and remove servers (EnableServerManagement)	`EnableServerManagement`	computer and user
Notify about new versions (EnableAutoUpdater)	`EnableAutoUpdater`	computer only
Trusted embedded media origins (TrustedEmbeddedMediaOrigins)	`TrustedEmbeddedMediaOrigins` subkey	computer and user

Group Policy in a domain

Copy antimatter.admx to the central store, \\<domain>\SYSVOL\<domain>\Policies\PolicyDefinitions, and antimatter.adml to its en-US folder.
In the Group Policy Management Editor, open Computer Configuration (or User Configuration) › Policies › Administrative Templates › Antimatter.
Edit a policy, choose Enabled and fill it in. For Servers, click Show and add one line per server: the value name is the tab name, the value is the server URL, such as https://chat.example.com.

Enabling Let people add and remove servers or Notify about new versions writes 1; disabling it writes 0.

Intune

In Devices › Configuration, use Import ADMX to import antimatter.admx with en-US\antimatter.adml. Then create a profile from Templates › Imported Administrative templates, and set the Antimatter policies in it.

A single computer, or a script

Copy the templates to C:\Windows\PolicyDefinitions to use them in gpedit.msc (Windows Pro and Enterprise). Or write the registry values directly, with a .reg file imported as an administrator (reg import antimatter-policies.reg), such as this one. The example-policies.reg file of the same folder has these values, with comments.

REGEDIT4

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Antimatter]
"EnableServerManagement"=dword:00000000
"EnableAutoUpdater"=dword:00000000
"DefaultUsername"="%USERNAME%"

[HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Antimatter\DefaultServerList]
"Chat"="https://chat.example.com"

macOS: a configuration profile

On macOS, the app reads its settings from the managed preferences of its bundle identifier, chat.antimatter.desktop, with the keys of the settings table. Deploy them with your MDM (Jamf, Intune, Kandji, Mosyle and others) as a configuration profile.

The resources/mac/mdm folder of the app's repository has an example profile, antimatter.mobileconfig. Edit its values, give it your own PayloadIdentifier and PayloadUUID values (uuidgen makes new UUIDs), and upload it as a custom profile.
Most MDMs also accept the keys alone, as a "custom settings" or "preference domain" payload for chat.antimatter.desktop. The same folder has them in example-managed-preferences.plist.

The settings inside the profile's payload:

<key>PayloadType</key>
<string>chat.antimatter.desktop</string>
<key>DefaultServerList</key>
<array>
    <dict>
        <key>name</key>
        <string>Chat</string>
        <key>url</key>
        <string>https://chat.example.com</string>
    </dict>
</array>
<key>DefaultUsername</key>
<string>%USER%</string>
<key>EnableServerManagement</key>
<false/>
<key>EnableAutoUpdater</key>
<false/>

Booleans can also be given as the integers 0 and 1.

Linux: the policy file

On Linux, the app reads /etc/antimatter-desktop/policies.json, a JSON object with the keys of the settings table:

{
    "DefaultServerList": [
        {"name": "Chat", "url": "https://chat.example.com"}
    ],
    "DefaultUsername": "%USER%",
    "EnableServerManagement": false,
    "EnableAutoUpdater": false,
    "TrustedEmbeddedMediaOrigins": []
}

Deploy it with your configuration management tool (Ansible, Puppet, Salt and others), owned by root, readable by everyone and writable by root only:

sudo install -d /etc/antimatter-desktop
sudo install -m 644 policies.json /etc/antimatter-desktop/policies.json

A file that isn't valid JSON is ignored, with a warning in the app's log. The Flatpak version doesn't see the host's /etc: give it read access, and it reads the file from /run/host/etc/antimatter-desktop/policies.json:

sudo flatpak override --system --filesystem=host-etc:ro chat.antimatter.desktop

Policies set for the Mattermost desktop app

On Windows, the app also reads the policies set for the Mattermost desktop app, under SOFTWARE\Policies\Mattermost, as a fallback. It reads them by place: the values directly under the policy key, the DefaultServerList subkey and the TrustedEmbeddedMediaOrigins subkey. For each of these three places, it reads the Mattermost key only when the Antimatter key has no values there, in either hive. So once one value is set directly under the Antimatter key, for example by the MSI's AUTOUPDATE property, none of the values directly under the Mattermost key are read. Move all your policies to the Antimatter key at once.

On macOS, the managed preferences of the Mattermost desktop app (com.mattermost.desktop) are not read: set them for chat.antimatter.desktop.

Unsigned builds

The desktop app's builds are not signed with a publisher certificate yet.

Windows. When a person opens a downloaded .exe or .msi, Microsoft Defender SmartScreen says that Windows protected the computer and names an unknown publisher. They choose More info, then Run anyway. SmartScreen checks files that people open after a download, so people don't see this warning when you deploy the app through SCCM, Intune or Group Policy. If your computers only run software from approved publishers (AppLocker or App Control for Business rules), allow the app by its installation path or file hash instead.
macOS. The app is signed ad hoc, but not notarised by Apple. The first time a person opens a downloaded copy, macOS says that it can't verify the app is free of malware, and doesn't open it. On macOS 15 and later, they open System Settings › Privacy & Security and choose Open Anyway. On earlier versions, they Control-click the app and choose Open. Gatekeeper only checks files marked as downloaded (with the quarantine attribute): when you install the app with your own tools, remove the mark in your installation script, with xattr -dr com.apple.quarantine /Applications/Antimatter.app.