Discordless

Automatically save local archives of Discord conversations and render them as HTML or DiscordChatExporter-frontend compatible JSON.

How it works

Discord uses an HTTPS REST API and Websocket API to transfer data. Discordless's mitmproxy addon, Wumpus In The Middle, intercepts that traffic and saves it locally as it is fetched. Discordless's exporter scripts can then render that saved data as HTML or DiscordChatExporter-frontend-compatible JSON for easy viewing.

Once you connect your Discord client to mitmproxy, Wumpus In The Middle automatically saves any data that your client fetches. Therefore, all messages, attachments, icons, etc. that you view will be saved. If you want to archive an entire channel at once, you will have to scroll through the whole thing, and maybe click on image attachments to load full-res versions.

Motivation

Discord has a history of arbitrary, unexpected, unappealable bans, which make you lose access to all your messages. If you want to keep records of your heartfelt conversations, you should probably save your own copies in case you lose access to your account or Discord shuts down someday. There are also a lot of communities that treat Discord as a documentation hub that ought to be archived.

There already exist tools to archive Discord channels, the most popular one being DiscordChatExporter, but they violate Discord's frustratingly strict Terms of Service. Exporting DMs with these tools requires "self-botting", which is a bannable offense - though it anecdotally seems to be rarely enforced against exporter tools. Nobody knows how Discord's auto-moderation and botting detection algorithms work, so I'd rather not risk it.

Discordless does not create any API requests or modify client behavior at all, so I don't think it violates Discord's Terms of Service, and it should be harder for Discord to detect. It also runs in the background, so you don't have to remember to backup regularly. It also works for mobile devices (as long as they are connected to Discordless's proxy server), which is nice for me since I primarily use Discord on my phone.

The archives are also "archive-grade" if you care about that; Discordless stores the raw API responses.

Install and setup - Debian-based Linux

You'll need to install Python, mitmproxy, and Discord's erlpack library.

Here are example commands you can use on Ubuntu. Assumes you use Python 3.9, but any 3.x version should work.

• Install Python: sudo apt install python3.9 python3.9-dev python3.9-idle
• Update pip: python3.9 -m pip install --upgrade pip
• Install mitmproxy: download the binaries from mitmproxy.org
• Install mitmproxy's certificate on every device with a Discord client that you want to archive with. (Sometimes you also have to install it on the browser level.)
• Install pyzstd, filetype and erlpack: python3.9 -m pip install pyzstd filetype erlpack

Install and setup - Mac

Mostly the same as the Debian-based Linux setup.

• Install Python 3.9+
• Install erlpack: pip install pyzstd filetype erlpack python-dateutil
• Install mitmproxy: brew install mitmproxy
• Run mitmproxy at least once to generate its certificate: mitmproxy
• Install mitmproxy's certificate: sudo security add-trusted-cert -d -p ssl -p basic -k /Library/Keychains/System.keychain ~/.mitmproxy/mitmproxy-ca-cert.pem

Install and setup - Windows

Make sure Python 3.9+ is installed. There is a problem with installing erlpack dependency on Windows, so Python 3.11+ is not supported. To check if Python is installed, open command prompt (Windows key + R, type cmd and press Enter) and run command:

py --version

If Python is not installed, download and install version 3.9.X or 3.10.X from official site. During installation, don't forget to check "Add Python 3.X to PATH".

Clone this project (Open folder where you want to clone this project in file explorer, press Alt + D, type cmd and press Enter)

git clone https://github.com/Roachbones/discordless
cd discordless

Update pip and install pyzstd, erlpack, filetype and python-dateutil dependencies:

py -m pip install --upgrade pip
py -m pip install python-dateutil filetype pyzstd erlpack

Install mitmproxy from official site. Mitmproxy installer for windows should automatically add mitmproxy, mitmdump and mitmweb to path. Close all opened command prompts to update PATH variable.

Open elevated command prompt (Windows key + R, type cmd and press Ctrl + Shift + Enter)

Generate certificates by running mitmproxy the first time:

mitmproxy.exe

Install mitmproxy certificate:

cd %UserProfile%\.mitmproxy\
certutil -addstore root mitmproxy-ca-cert.cer

Install and setup - Docker

You'll need to install Docker and Docker Compose. Clone this repository, then run:

docker compose up --build

Your mitmproxy certificate will be stored in ~/.mitmproxy. Install mitmproxy's certificate on every device with a Discord client that you want to archive with. (Sometimes you also have to install it on the browser level.)

Usage

Step one: data collection - Debian based Linux

Start the proxy server: mitmdump -s wumpus_in_the_middle.py --listen-port=8080 --allow-hosts '^(((.+\.)?discord\.com)|((.+\.)?discordapp\.com)|((.+\.)?discord\.net)|((.+\.)?discordapp\.net)|((.+\.)?discord\.gg))(?::\d+)?$'

(For Docker users, as long as your server is up, you do not need to run this.)

Start Discord, connected to the proxy server. If you're on a PC, you can do discord --proxy-server=localhost:8080 to start an instance of Discord connected to the proxy without having to configure your whole computer to use the proxy. You can replace localhost:8080 with some other address if the proxy server is running on a different device. If you're on mobile, or otherwise don't want to use that commandline argument, then configure the whole device to use the proxy server in the network settings. Due to the --allow-hosts argument we pass to mitmproxy, it should not interfere much with non-Discord traffic.

You can tell that data collection is working if traffic_archive/requests/ starts filling up.

Always launching with proxy server setting

To make this the default way to launch Discord, assuming your Discord is installed using Flatpak, first create a copy of Discord's .desktop file: cp /var/lib/flatpak/exports/share/applications/com.discordapp.Discord.desktop ~/.local/share/applications/com.discordapp.Discord.desktop

Then edit this new file, locate the Exec line, and add the --proxy-server parameter. This could look like this: Exec=/usr/bin/flatpak run --branch=stable --arch=x86_64 --command=com.discordapp.Discord --file-forwarding com. discordapp.Discord --proxy-server=localhost:8080 @@u %U @@

Step one: data collection - Windows

Start the proxy server in the first command prompt (Windows key + R, type cmd and press Enter):

mitmdump -s wumpus_in_the_middle.py --listen-port=8080 --allow-hosts "^(((.+\.)?discord\.com)|((.+\.)?discordapp\.com)|((.+\.)?discord\.net)|((.+\.)?discordapp\.net)|((.+\.)?discord\.gg))(?::\d+)?$"

Discord executable is not in PATH; we need to find it manually. Open second command prompt (Windows key + R, type cmd and press Enter)

cd %LocalAppData%\Discord\app-<version>\
cd app-
[tab]
[enter]
discord --proxy-server=localhost:8080

Step two: export archived traffic to DCE-style JSON (or HTML)

If Wumpus In The Middle is still running, restart it (ctrl+c in the terminal) to ensure it flushes its file buffers. Then run exporter.py to turn the data in traffic_archive/ into an export.

DCE-style JSON

python3 exporter.py dcejson-exporter reads the data in traffic_archive and outputs a DiscordChatExporter-style JSON export to dcejson_exports/export_{current Unix time}/. You can feed that export into DiscordChatExporter-frontend to neatly display it in a Discord-style interface.

(For Docker users, you can run this by running docker exec discordless-discordless-1 python exporter.py dcejson-exporter && docker restart discordless-dcebox-frontend-1. You can do this in any directory, though the files will be stored in $PROJECT_ROOT/dcejson_exports.)

Run python3 exporter.py dcejson-exporter -h to see additional export options.

HTML

There are two HTML backends: The classical HTML exporter and HTMemL.

Classical HTML

HTML exporting is half-baked at this point; embeds do not work, and there's no pagination. It can show some extra data, though, like message edit history.

You can run python3 exporter.py html-exporter similar to the DCE-JSON option.

Run python3 exporter.py html-exporter -h to see additional export options.

HTMemL

HTMemL is an optimized HTML exporter that does not use nearly as much memory as the classical HTML exporter. It has been built to export a discord server as a public message archive (a bit like a forum or mailing list archive). It supports pagination, attachments, and even some discord markdown. However, it does come with differences compared to the classical exporter: It d