{"id":16828703,"url":"https://github.com/hifi/heisenbridge","last_synced_at":"2025-05-15T11:08:20.195Z","repository":{"id":40248137,"uuid":"356770814","full_name":"hifi/heisenbridge","owner":"hifi","description":"a bouncer-style Matrix IRC bridge","archived":false,"fork":false,"pushed_at":"2025-05-09T10:15:47.000Z","size":411,"stargazers_count":271,"open_issues_count":72,"forks_count":37,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-13T10:58:36.941Z","etag":null,"topics":["appservice","bouncer","bridge","irc","matrix","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hifi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-04-11T05:00:18.000Z","updated_at":"2025-05-09T10:15:51.000Z","dependencies_parsed_at":"2023-02-19T16:01:04.781Z","dependency_job_id":"8aa6b10a-ee28-4bd5-9500-133436aa3acc","html_url":"https://github.com/hifi/heisenbridge","commit_stats":{"total_commits":396,"total_committers":16,"mean_commits":24.75,"dds":"0.11868686868686873","last_synced_commit":"ba30389859a2fabdba404dfed70e8ddd3bf9fab2"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hifi%2Fheisenbridge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hifi%2Fheisenbridge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hifi%2Fheisenbridge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hifi%2Fheisenbridge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hifi","download_url":"https://codeload.github.com/hifi/heisenbridge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254328384,"owners_count":22052632,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["appservice","bouncer","bridge","irc","matrix","python"],"created_at":"2024-10-13T11:28:01.992Z","updated_at":"2025-05-15T11:08:20.173Z","avatar_url":"https://github.com/hifi.png","language":"Python","funding_links":[],"categories":["Frameworks"],"sub_categories":["Bridges"],"readme":"Heisenbridge\n============\n\na bouncer-style Matrix IRC bridge.\n\n\u003cimg align=\"right\" width=\"220\" height=\"250\" src=\"https://raw.githubusercontent.com/hifi/heisenbridge/master/logo/heisenbridge-light-transparent.png\"\u003e\n\nHeisenbridge brings IRC to Matrix by creating an environment where every user connects to each network individually like they would with a traditional IRC bouncer.\nSimplicity is achieved by exposing IRC in the most straightforward way as possible where it makes sense so it feels familiar for long time IRC users.\n\nPlease file an issue when you find something is missing or isn't working that you'd like to see fixed. Pull requests are more than welcome!\n\nSupport and development discussion in [#heisenbridge:vi.fi](https://matrix.to/#/#heisenbridge:vi.fi) on Matrix or by joining [#heisenbridge](https://web.libera.chat/?channels=#heisenbridge) on [Libera.Chat](https://libera.chat) IRC network.\nThe IRC channel is plumbed with Heisenbridge to Matrix using the relaybot mode.\n\nFeatures\n--------\n* \"zero configuration\" - no databases or storage required\n* brings IRC to Matrix rather than Matrix to IRC - not annoying to folks on IRC\n* completely managed through admin room - just DM `@heisenbridge`!\n* channel management through bridge bot - type `heisenbridge: help` to get started!\n* online help within Matrix\n* access control for local and federated users\n* configurable IRC user synchronization in rooms (fully synced on connect, half synced on join or lazy on talk)\n* tested with up to 2000 users in a single channel\n* optional room plumbing with single puppeting on Matrix \u003c-\u003e relaybot on IRC\n* IRCnet !channels _are_ supported, you're welcome\n* any number of IRC networks and users technically possible\n* channel customization by setting the name and avatar\n* TLS support for networks that have it\n* customizable ident support\n* configurable pillifying of IRC nicks\n* long message splitting directly to IRC\n* smart message formatting from Matrix to IRC using IRC conventions\n* smart message edits from Matrix to IRC by sending only corrections\n* automatic identify/auth with server password or automatic command on connect\n* SASL plain authentication\n* CertFP authentication\n* CTCP support\n* SOCKS proxy configuration per server\n* bridge managed spaces to organize your channels and PMs within a network\n\nComparison\n----------\n\nTo help understand where Heisenbridge is a good fit here's a feature matrix of some of the key differences between other popular solutions:\n\n|                         | Matrix |  IRC | Appservice | Ratelimit | Self-host | Permissions  |\n|-------------------------|:------:|:----:|:----------:|:---------:|:---------:|--------------|\n| Heisenbridge (bouncer)  | one    | one  | yes        | no        | yes       | IRC only     |\n| Heisenbridge (relaybot) | many   | one  | yes        | IRC       | yes       | separate     |\n| matrix-appservice-irc   | many   | many | yes        | no        | no        | synchronized |\n| matterbridge            | one    | one  | no         | both      | only      | separate     |\n\n**Matrix** = actual users on Matrix  \n**IRC** = connected users to IRC from Matrix  \n**Appservice** = runs as an appservice (requires a homeserver)  \n**Ratelimit** = perceived ratelimiting in default setup (Matrix/IRC)  \n**Self-host** = is it recommended to run your own instance  \n**Permissions** = how room/channel permissions are managed (Matrix/IRC)  \n\nHeisenbridge in bouncer mode has one direct Matrix user per IRC connection and IRC users are puppeted on Matrix.\nThe Matrix users identity is directly mapped to IRC and they are in full control.\nThere are no Matrix side permission management in this mode as all channels and private messages are between the Matrix user and the bridge.\nMultiple authorized Matrix users can use the bridge separately to create their own IRC connections.\n\nHeisenbridge in relaybot mode is part of a larger Matrix room and puppets everyone from IRC separately but still has only one IRC connection for relaying messages from Matrix.\nMatrix users' identities are only relayed through the messages they send.\nPermissions in this mode are separate meaning the bridge needs to be given explicit permission to join a Matrix room if it's not public.\nThe bridge only requires enough power levels to invite puppets (if the room is invite-only) and for them to be able to talk with the default power level they get.\nSingle authorized Matrix user manages the relaybot with Heisenbridge.\n\n[matrix-appservice-irc](https://github.com/matrix-org/matrix-appservice-irc) runs in full single puppeting mode where both IRC and Matrix users are puppeted both ways.\nThe Matrix users identity is directly mapped to IRC and they are in full control.\nThis method of bridging creates multiple IRC connections which makes is mostly transparent for both sides of the bridge.\nAs the room and channel permissions are synchronized between IRC and Matrix (where applicable) means a Matrix user joining a Matrix room needs to be able to connect and join the IRC channel through the bridge as well.\nAny Matrix user joining plumbed or portal IRC rooms are automatically connected to the IRC network.\n\n[matterbridge](https://github.com/42wim/matterbridge) is a bot which connects to each network as a single user and is fairly easy and quick to setup by anyone.\nBoth IRC and Matrix users' identities are only relayed through the messages they send.\nThe bot operator manages everything and does not require any user interaction on either side.\n\nPyPI\n----\nGitHub releases are automatically published to [PyPI](https://pypi.org/project/heisenbridge/):\n\n```sh\npip install heisenbridge\n```\n\nDocker\n------\nThe master branch is automatically published to [Docker Hub](https://hub.docker.com/r/hif1/heisenbridge):\n```sh\ndocker pull hif1/heisenbridge\ndocker run --rm hif1/heisenbridge -h\n```\n\nEach GitHub release is also tagged as `x.y.z`, `x.y` and `x`.\n\nAn example docker-compose setup is in [docker-compose/](docker-compose/).\n\nAdditionally, if you use [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy) to deploy your Synapse server, you can use it to integrate Heisenbridge as well - just follow the [relevant docs](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook-bridge-heisenbridge.md)\n\nUsage\n-----\n```\nusage: python -m heisenbridge [-h] [-v] (-c CONFIG | --version)\n                              [-l LISTEN_ADDRESS] [-p LISTEN_PORT] [-u UID]\n                              [-g GID] [-i] [--identd-port IDENTD_PORT]\n                              [--generate] [--generate-compat] [--reset]\n                              [--safe-mode] [-o OWNER]\n                              [homeserver]\n\na bouncer-style Matrix IRC bridge (v1.14.5.dev4+gb9c79bb)\n\npositional arguments:\n  homeserver            URL of Matrix homeserver (default:\n                        http://localhost:8008)\n\noptions:\n  -h, --help            show this help message and exit\n  -v, --verbose         logging verbosity level: once is info, twice is debug\n                        (default: 0)\n  -c CONFIG, --config CONFIG\n                        registration YAML file path, must be writable if\n                        generating (default: None)\n  --version             show bridge version\n  -l LISTEN_ADDRESS, --listen-address LISTEN_ADDRESS\n                        bridge listen address (default: as specified in url in\n                        config, 127.0.0.1 otherwise) (default: None)\n  -p LISTEN_PORT, --listen-port LISTEN_PORT\n                        bridge listen port (default: as specified in url in\n                        config, 9898 otherwise) (default: None)\n  -u UID, --uid UID     user id to run as (default: None)\n  -g GID, --gid GID     group id to run as (default: None)\n  -i, --identd          enable identd service (default: False)\n  --identd-port IDENTD_PORT\n                        identd listen port (default: 113)\n  --generate            generate registration YAML for Matrix homeserver\n                        (Synapse)\n  --generate-compat     generate registration YAML for Matrix homeserver\n                        (Dendrite and Conduit)\n  --reset               reset ALL bridge configuration from homeserver and\n                        exit\n  --safe-mode           prevent appservice from leaving invalid rooms on\n                        startup (for debugging) (default: False)\n  -o OWNER, --owner OWNER\n                        set owner MXID (eg: @user:homeserver) or first talking\n                        local user will claim the bridge (default: None)\n```\n\nGenerate a registration file to use with your homeserver using the `--generate` switch.\nIf you are using Dendrite or Conduit prefer `--generate-compat` as otherwise you can't talk with Heisenbridge.\n\n**With the amount of showstopper bugs in Dendrite it's not officially supported by Heisenbridge at this time. When they get fixed this notice will be removed. If you hit a bug on Dendrite, please reproduce it on Synapse or Conduit before reporting it against Heisenbridge. Thank you.**\n\nBoth your homeserver and Heisenbridge use the same registration file to configure their shared secrets.\nWith Heisenbridge you need to use the generated registration file with the `--config` switch on startup.\nIf you are running Docker a shared volume mount is adviced for the registration file that both containers can access.\n\nCommunication between the homeserver and any bridge is bi-directional and requires that both can access each other directly over the network.\nBy default Heisenbridge expects your homeserver to be accessible on localhost port 8008/TCP and the bridge itself listens on localhost port 9898/TCP.\nYou can override these defaults using the appropriate command line options but prefer local addresses when possible.\nIf you are running Docker the homeserver is likely on a different hostname inside the Docker network so change it accordingly by setting the positional argument on startup.\n\nPlease note that the URL for Heisenbridge in the registration file is used by the homeserver to connect to it so make sure it is correct and accessible from where the homeserver is running.\n\nYou also need to make sure the configuration of your homeserver does not force all rooms to be created with encryption on, as Heisenbridge currently does not support encryption.\nIf you force encryption, Heisenbridge will be unable to respond to your commands.\nFor example, if you use Synapse, make sure `encryption_enabled_by_default_for_room_type` is set to `off`. You can still enable encryption in other rooms, it will just not be the default.\n\nIf for whatever reason you run Heisenbridge over the internet and require HTTPS you need to put Heisenbridge behind a reverse proxy that does TLS termination as it doesn't itself support loading a TLS certificate.\n\nFor [Synapse](https://github.com/matrix-org/synapse) see their [installation instructions](https://github.com/matrix-org/synapse/blob/develop/docs/application_services.md) for appservices.\n\nFor [Conduit](https://gitlab.com/famedly/conduit) see their [installation instructions](https://gitlab.com/famedly/conduit/-/blob/next/APPSERVICES.md) for appservices.\n\nInstall\n-------\n\n1. Install Python 3.10 or newer\n2. Install dependencies in virtualenv\n\n   ```bash\n   virtualenv venv\n   source venv/bin/activate\n   pip install heisenbridge\n   ```\n\n3. Generate registration YAML\n\n   ```bash\n   python -m heisenbridge -c /path/to/synapse/config/heisenbridge.yaml --generate\n   ```\n\n4. Add `heisenbridge.yaml` to Synapse appservice list\n5. (Re)start Synapse\n6. Start Heisenbridge\n\n   ```bash\n   python -m heisenbridge -c /path/to/synapse/config/heisenbridge.yaml\n   ```\n\n7. Start a DM with `@heisenbridge:your.homeserver` to get online usage help. Example commands to join a new network:\n\n   ```\n   ADDNETWORK IRCnet\n   ADDSERVER IRCnet ssl.ircnet.io 6697 --tls\n   OPEN IRCnet\n   ```\n\n   You will be invited to a room where you can `CONNECT` and `JOIN #some-channel`\n\nTo update your installation, run `pip install --upgrade heisenbridge`\n\nDevelop\n-------\n\n1. Install Python 3.10 or newer\n2. Install dependencies\n\n   ```bash\n   virtualenv venv\n   source venv/bin/activate\n   pip install -e .[dev,test]\n   ```\n\n3. (Optional) Set up pre-commit hooks\n\n   ```bash\n   pre-commit install\n   ```\n\nThe pre-commit hooks are run by the CI as well.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhifi%2Fheisenbridge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhifi%2Fheisenbridge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhifi%2Fheisenbridge/lists"}