Matrix <--> IRC Bridge
This is an IRC bridge for Matrix using the Application Services (AS) API. If you're upgrading from an old release, be sure to read the CHANGELOG as there may be breaking changes between releases.
This bridge will pass all IRC messages through to Matrix, and all Matrix messages through to IRC. It is highly configurable and is currently used on the matrix.org homeserver to bridge a number of popular IRC networks including Freenode and Moznet.
There are 4 stages to setting up the IRC bridge which are outlined below.
For more information, check out the how-to guide.
To install all dependencies and add a binary
$ npm install matrix-appservice-irc --global
git clone this repository on the
master branch, then run
npm install. If
you use this method, the bridge can be run via
- Node.js v4.5 or above.
- A Matrix homeserver you control running Synapse v0.18.5-rc3 or above.
The bridge must be configured before it can be run. This tells the bridge where to find the homeserver and how to bridge IRC channels/users.
config.yamlto point to your homeserver and IRC network of choice.
The bridge needs to generate a registration file which can be passed to the homeserver to tell the homeserver which Matrix events the bridge should receive. Execute the following command:
$ node app.js -r -f my_registration_file.yaml -u "http://where.the.appservice.listens:9999" -c config.yaml -l my_bot Loading config file /home/github/matrix-appservice-irc/config.yaml Output registration to: /home/github/matrix-appservice-irc/my_registration_file.yaml
More information on the CLI args can be found by running
$ node app.js --help
This will create a registration YAML file. Edit your homeserver config file (e.g.
point to this registration file:
# homeserver.yaml app_service_config_files: ["my_registration_file.yaml"]
Finally, the bridge can be run using the following command:
$ node app.js -c config.yaml -f my_registration_file.yaml -p 9999
What does it do?
On startup, the bridge will join Matrix clients to the IRC channels specified in the configuration file. It will then listen for incoming IRC messages and forward them through to Matrix rooms. Each real Matrix user is represented by an IRC client, and each real IRC client is represented by a Matrix user. Full two-way communication in channels and PMs are supported, along with a huge array of customisation options.
For more information on how you can customise the bridge, check out the how-to guide.
To join a channel on an IRC network configured for public use:
- Join a room with the alias
#irc_#python:example.com. The template for this can be configured at
For the publicly bridged IRC networks on matrix.org, the options are:
/join #freenode_#somewhere:matrix.org(for freenode)
/join #mozilla_#somewhere:matrix.org(for moznet)
To send a PM to someone on an IRC network:
- Start a conversation with a user ID
@irc_Alice:example.com. The template for this can be configured at
See the sample config file for an explanation of the configuration options available.
Please see the CONTRIBUTING file for information on contributing.