Unifier
Install guide for Unifier v3.0.0 and newer.
This guide is for Unifier v3.0.0 and newer. If you're installing an older version of Unifier, consult the legacy guide instead.
Used the (Legacy) Installer?
Unifier cannot be installed using the legacy installer. Please use the integrated installer instead.
Requirements
Minimum system requirements
Memory requirements will depend on many factors such as but not limited to cached messages and number of servers the bot is in.
Unifier requires the following:
64-bit CPU that can run Python 3.9 or newer
At least 100MB of available RAM, meaning excluding RAM already being used by the system and other apps
An internet connection
Python 3.9 or newer:
Optimized and Balanced installations require Python 3.12 or above.
Stable requires Python 3.9 or above.
Recommended system requirements
We recommend the following for Unifier:
64-bit CPU based on x86_64 or arm64/aarch64 that can run Python 3.12 or newer
20 Mbps or faster internet connection
Python 3.12 or newer
Running Unifier
To run or install Unifier, you will need to launch the "bootloader". The bootloader checks if there is already a Unifier installation present before starting Unifier, otherwise it will run the installer.
We have plans to provide a Docker image in the near future.
Self-hosted
On Linux, macOS, or any other compatible systems that use bash, run ./run.sh. We recommend you run this in a screen, so Unifier can keep running even after you close the terminal or SSH session to your host server.
On Windows, run ./run.bat.
Managed (Pterodactyl)
Pterodactyl containers run on top of a Linux system, meaning that it can run bash programs. However, some Eggs might not support this, and may restrict you to running Python files only.
If you can customize the startup command, set it to sh run.sh.
If you can customize the "App PY file" field, set it to boot/bootloader.py.
Start the server once one of the above have been set.
Installing Unifier
From v3.0.0, the integrated installer automatically handles installing dependencies.
Your console should output the following if no Unifier installation has been detected, after asking you which installation option you would like:
For most cases, we recommend using the Balanced option, as it includes additional libraries for performance optimization and the latest tested version of Nextcord. If you want the absolute best experience from Unifier, you should use the Optimized option, which is similar to Balanced but includes the very latest version of Nextcord. However, if these options cause issues, or you want maximum stability, you should choose Stable which only includes the essentials.
To choose an installation option, type its corresponding option number, then press enter. After you have chosen the installation option, you will be able to choose the Python environment you want to use, if your host system uses Linux or macOS.
The default environment will be marked with a star. Although you can choose any of the supported versions, we recommend using the latest version possible (this will be at the top of the list) for best performance. You will also be asked if you want to create a virtual environment for the selected Python environment, or if you want to use the existing environment if it exists in the install directory.
Once you've selected your environment (or if you're on Windows), you should see the confirmation dialog.
Type "y" to install Unifier, then follow the instructions provided by the installer. After installation is complete, Unifier will automatically start.
Using System Manager
WARNING: Do NOT grant anyone access to admin commands! Certain admin commands have the potential to ruin your system if used maliciously!
We STRONGLY ENCOURAGE you to NOT modify System Manager whatsoever for this very reason.
Unifier has a powerful System Manager to let instance owners effortlessly run commands and manage extensions.
Here's some basic commands to get you started:
u!reload <extension>: Reloads an extension, useful for updating extensions without restarting the entire bot.u!eval <command>: Evaluates a Python command. Only use if you know what you're doing!u!install <plugin>Installs a plugin from a Git repository. A valid plugin.json file is required.u!uninstall <plugin>: Uninstalls a plugin.u!upgrade [plugin] [args]: Upgrades a plugin. If all arguments are left empty, it will upgrade Unifier.u!shutdown: Shuts the bot down.u!reboot: Reboots the bot.
Further setup
Installing Revolt Support
"Revolt Support" references the Unifier Revolt Support extension, not the Revolt support team.
First, you will need to create a Revolt bot, then add its token to the tokens list. To do this, shut down the bot (if it's already running), then run:
sh run.sh --tokenson Linux/macOS, or./run.bat --tokenson Windows
to open the token manager. Enter your token encryption password, then type add-token, then add a token under the TOKEN_REVOLT key.
You will also need to add user IDs of admins as admin_ids, as well as the user ID of the bot's owner. As Unifier's admins list allow both integers and strings, you can have both Discord and Revolt users under the same list. Your config.toml file should now look something like this:
As Revolt uses alphanumeric IDs, rather than integers, you will need to save admin IDs as strings.
After starting the bot, you can run u!install https://github.com/UnifierHQ/unifier-revolt to install Revolt Support.
Misconfiguration, such as a missing Revolt bot token, will result in the upgrade failing. This is caused by the System Manager being unable to start Revolt Support, and in most cases can be fixed by running u!load bridge_revolt. If this does not help, run u!restart.
If all goes well, Revolt Support will be running and your Revolt bot will be up and running. You can always stop Revolt Support by running u!stop-revolt.
Alternatively, you can also run u!unload bridge_revolt to stop Revolt Support.
If you wish to stop Revolt Support from loading on boot, please uninstall the Plugin. All dependencies and configuration files will be retained.
Installing Guilded Support
"Guilded Support" references the Unifier Guilded Support extension, not the Guilded support team.
As Guilded Support is programmed similarly to Revolt Support, the installation process is near identical.
First, you will need to create a Guilded bot, then add its token to the tokens list. To do this, shut down the bot (if it's already running), then run:
sh run.sh --tokenson Linux/macOS, or./run.bat --tokenson Windows
to open the token manager. Enter your token encryption password, then type add-token, then add a token under the TOKEN_GUILDED key.
You will also need to add user IDs of admins as admin_ids, as well as the user ID of the bot's owner. As Unifier's admins list allow both integers and strings, you can have both Discord and Guilded users under the same list. Your config.toml file should now look something like this:
As Guilded uses alphanumeric IDs, rather than integers, you will need to save admin IDs as strings.
After starting the bot, you can run u!install https://github.com/UnifierHQ/unifier-guilded to install Guilded Support.
Misconfiguration, such as a missing Guilded bot token, will result in the upgrade failing. This is caused by the System Manager being unable to start Revolt Support, and in most cases can be fixed by running u!load bridge_guilded. If this does not help, run u!restart.
If all goes well, Guilded Support will be running and your Guilded bot will be up and running. You can always stop Guilded Support by running u!stop-guilded.
Alternatively, you can also run u!unload bridge_guilded to stop Guilded Support.
If you wish to stop Guilded Support from loading on boot, please uninstall the Plugin. All dependencies and configuration files will be retained.
Upgrading Unifier
To upgrade Unifier, you can use the System Extension/Upgrader to update the bot to the latest version. Run u!upgrade to check for upgrades, then upgrade if one is available. You can also run u!upgrade system force to upgrade to the newest files in the Unifier repo, regardless of whether a new upgrade is available or not.
Assigning moderators
To help keep your chat clean, Unifier lets you add moderators that can delete messages and temporarily or permanently ban users from Unified Chat. Admins can assign them by running u!addmod @user, or unassign them by running u!removemod @user. The changes will be reflected in data.json automatically.
Making a room
Unified Chat depends on "rooms". If you send something in a channel linked to the main room, they will be sent to all other channels linked to the same room.
Rooms can be created by admins only. To create a room, run u!make <room>. You can add rules using u!addrule <room> <rule>, lock authors to admins only using u!roomlock <room>, and restrict people who can connect to your room to admins only by using u!roomrestrict <room>.
Next steps
Congratulations, your Unifier instance is ready to go! Follow the Getting started for the official instance to connect your servers.
Here's some further guides you can follow to make the best out of Unifier:
Moderation toolsGlobal emojisUpgrading UnifierTroubleshooting
Bot crash: "no module named ulid/typing-extensions/aenum"
Python's pip, for some reason, may not have installed revolt.py's dependencies correctly. To solve this, you can manually install the three extensions.
If you're using Pterodactyl panel to manage your Unifier server, add ulid typing-extensions aenum to "Additional Python packages". This will ensure that the missing libraries are installed on boot.
Cannot install Revolt/Guilded Support: repository URL or plugin.json file is invalid
Please check that the URL exactly matches what we've provided. If it does match, please make sure if you have git installed on your system.
If the issue persists after installing Git, please restart Unifier. If the issue persists even after restart, or Git was already installed when you got the error, please open a GitHub issue on the correct repository.
Winloop failed to build
This is for Windows users only. Unifier will use uvloop on Linux and macOS hosts, which is a different library.
If winloop fails to build for whatever reason, you should use the Stable installation. This won't limit any features, but it will probably be slower than Optimized and Balanced installations.
Unifier is not reaching its advertised speeds
When Unifier starts up, it will have no Webhooks in its Webhook cache. This means that for each server, Unifier will need to fetch the bridge Webhooks from Discord's API, which adds additional latency. However, once you send your first message, Unifier will cache as many Webhooks as it can, so that subsequent messages can be bridged even faster.
Also, consider using the Optimized installation. It includes a lot of extra libraries to speed things up.
Unifier is still not reaching its advertised speeds
Unifier's bridge speed will vary depending on various factors such as but not limited to your server specifications, server region, and Discord API performance. Most of the time, though, Unifier should be able to reach around 20-25MPS outside the US, and possibly 30+MPS within the US.
We were able to achieve 20MPS consistently, peaking at 26MPS, with our main VPS that we use to host the official Unifier instance:
Type: VPS
Provider: Akamai Connected Cloud (formerly Linode)
Location: Frankfurt, Germany
CPU: Shared 2-core AMD EPYC 7713
RAM: 4 GB
Network in/out: 40 Gbps/4 Gbps
We got these speeds in real-world conditions, so others should be able to too.
Last updated