Say My Name: Heisenbridge, IRC and Breaking Free from Discord

October 14, 2025 · 6 min read · Nick Schmidt (oneguynick)

Table of contents

  • Why I left Discord
  • A quick tour of Heisenbridge
  • The commands I ran
  • Startup and maintenance
  • Final thoughts

I love tools. I also hate lock-in. When I am debugging a project and discover the community talks behind the walls of a closed source app, I want to scream. Discord is convenient, sure, but it is not where open source projects should live. It fragments conversation and hands control to a single vendor.

I have been moving my comms to Matrix for a while, and one of the last pieces I wanted to stitch into the new setup was IRC. IRC is where a lot of communities still live. It is simple, battle tested, and honest. Heisenbridge is a tiny Python bridge that makes Matrix sit at the IRC table without pretending to be something it is not.

Below is how I set it up on OpenBSD. This is what I actually ran on my machine. It is not a fancy installer script, it is a recipe. If you want to follow along, make a cup of tea and let us proceed.

Why I left Discord

  • Proprietary client, proprietary ecosystem, and the community behind it is fenced off.
  • It forces newcomers into a specific UI and tracking model.
  • When things go wrong you cannot inspect the plumbing, because the plumbing is hidden.
  • Federation and open protocols give you freedom - losing that feels like trading flexibility for laziness.

A quick tour of Heisenbridge

Heisenbridge gives Matrix a way to connect to IRC networks like LiberaChat. It creates a Matrix application service user and acts like an IRC client for those channels. Your Matrix rooms end up bridged to IRC channels, and you keep your client, your logs and your sanity.

The heisenbridge project is here: https://github.com/hifi/heisenbridge

The commands I ran - exact and unglossed

  1. Create a dedicated system user for the bridge
1

doas useradd -g =uid -c "heisenbridge irc bouncer" -L daemon -s /sbin/nologin -d /home/heisenbridge -m _heisenbridge
  1. Install the virtualenv helper
1

doas pkg_add py3-virtualenv
  1. Become the heisenbridge user and create a Python virtualenv
1
2
3
4
5
6

doas -u _heisenbridge /usr/local/bin/bash -l
python3 -m venv ~/pyenv
echo "source ~/pyenv/bin/activate" >> ~/.profile
source ~/pyenv/bin/activate
pip install --upgrade pip
pip install heisenbridge
  1. Generate the registration file for Synapse
1
2

python -m heisenbridge -c heisenbridge-registration.yaml --generate
doas cp heisenbridge-registration.yaml /var/synapse/

Add the file path to app_service_config_files in your Synapse config then restart Synapse to load it.

  1. Start heisenbridge manually to sanity check it
1

python -m heisenbridge -c heisenbridge-registration.yaml

Open a chat to the bot account that was created. It will look like:

1

@heisenbridge:matrix.yourdomain.example
  1. In the Matrix chat, create a network and server for LiberaChat
1
2
3

ADDNETWORK LiberaChat
ADDSERVER  LiberaChat irc.libera.chat 6697 --tls
OPEN       LiberaChat

You should get feedback from LiberaChat. Then run

1
2
3
4

color
NICK yournickname
connect
join #openbsd

If you see the welcome message you are in business. Your Matrix client is now part of the IRC channel. Keep calm and answer questions about OpenBSD.

Make it persistent - OpenBSD style

I made a simple rc.d script at /etc/rc.d/matrix_heisenbridge so the bridge starts on boot. The file looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

#!/bin/ksh

daemon_execdir="/home/heisenbridge"
daemon_logfile="/var/log/matrix-heisenbridge"
daemon="/home/heisenbridge/pyenv/bin/python -m heisenbridge -c heisenbridge-registration.yaml"
daemon_user="_heisenbridge"

. /etc/rc.d/rc.subr

rc_bg=YES
rc_reload=NO
rc_stop_signal=INT

rc_cmd $1

Make it executable and test it

1
2
3

chmod 0555 /etc/rc.d/matrix_heisenbridge
rcctl -d start matrix_heisenbridge
rcctl enable matrix_heisenbridge

If rcctl shows errors check the log at /var/log/matrix-heisenbridge and the usual syslog files. In my run I had a small permission issue on the registration file. Fix that with chmod or chown as appropriate.

Maintenance - updates that do not suck

I keep heisenbridge in a virtualenv so updating is trivial. I use a tiny update script in the heisenbridge home directory.

Create ~/update as the heisenbridge user with these contents

1
2
3
4

pip install -U pip
pip install -U setuptools
pip install -U wheel
pip install -U heisenbridge

Make it executable

1
2

chmod 0750 ~/update
doas -u _heisenbridge bash -l /home/heisenbridge/update

I add the update call to /etc/weekly.local so it runs when I do system maintenance

1
2

next_part "Upgrade heisenbridge:"
doas -u _heisenbridge bash -l /home/heisenbridge/update

Tune the cadence to your patching policy. Monthly is fine if you prefer fewer updates.

Caveats and troubleshooting notes

  • Make sure Synapse has the registration file path and that the YAML is valid.
  • If you run into strange permission errors, check the user that the bridge runs under and the registration file ownership.
  • TLS to IRC is flaky on occasion. If you cannot connect try an alternate server or double check your firewall.
  • Heisenbridge logs to stdout by default. Redirect or wrap it if you want to keep clean logs.

Final thoughts

I like having a stack I control. I like waking up and knowing my chat rooms are not locked behind a corporate UI. Heisenbridge is small, sensible and gets the job done. You keep Matrix as the place you live and IRC as the place you visit.

From field to cloud, own your comms and keep them open.