{"id":13557563,"url":"https://github.com/matrix-org/pantalaimon","last_synced_at":"2025-05-15T09:08:41.930Z","repository":{"id":34446853,"uuid":"177604275","full_name":"matrix-org/pantalaimon","owner":"matrix-org","description":"E2EE aware proxy daemon for matrix clients.","archived":false,"fork":false,"pushed_at":"2025-04-15T15:34:27.000Z","size":2879,"stargazers_count":301,"open_issues_count":49,"forks_count":44,"subscribers_count":26,"default_branch":"master","last_synced_at":"2025-05-13T10:55:22.019Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"2019-03-25T14:37:20.000Z","updated_at":"2025-04-30T12:29:17.000Z","dependencies_parsed_at":"2024-01-06T20:46:20.104Z","dependency_job_id":"c979e627-e983-43ef-8fa6-71d5ea259454","html_url":"https://github.com/matrix-org/pantalaimon","commit_stats":{"total_commits":487,"total_committers":26,"mean_commits":18.73076923076923,"dds":"0.18891170431211501","last_synced_commit":"257ef6a2e5e5668cd43347037c09ba036f91d997"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fpantalaimon","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fpantalaimon/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fpantalaimon/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fpantalaimon/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/pantalaimon/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254310520,"owners_count":22049470,"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":["hacktoberfest"],"created_at":"2024-08-01T12:04:25.294Z","updated_at":"2025-05-15T09:08:36.913Z","avatar_url":"https://github.com/matrix-org.png","language":"Python","funding_links":[],"categories":["Python","Encryption","E2EE stuff","others"],"sub_categories":["Single Purpose Bots","Federation data"],"readme":"pantalaimon\n===========\n\nPantalaimon is an end-to-end encryption aware Matrix reverse proxy daemon.\nPantalaimon acts as a good man in the middle that handles the encryption for you.\n\nMessages are transparently encrypted and decrypted for clients inside of\npantalaimon.\n\n![Pantalaimon in action](docs/pan.gif)\n\nInstallation\n============\n\nThe [Olm](https://gitlab.matrix.org/matrix-org/olm) C library is required to\nbe installed before installing pantalaimon.\n\nIf your distribution provides packages for libolm it is best to use those, note\nthat a recent version of libolm is required (3.1+). If your distribution doesn't\nprovide a package building from source is required. Please refer to the Olm\n[readme](https://gitlab.matrix.org/matrix-org/olm/blob/master/README.md)\nto see how to build the C library from source.\n\nInstalling pantalaimon works like usually with python packages:\n\n    python setup.py install\n\nor you can use `pip` and install it with:\n```\npip install .[ui]\n```\n\nIt is recommended that you create a virtual environment first or install dependencies\nvia your package manager. They are usually found with `python-\u003cpackage-name\u003e`.\n\nPantalaimon can also be found on pypi:\n\n    pip install pantalaimon\n\nPantalaimon contains a dbus based UI that can be used to control the daemon.\nThe dbus based UI is completely optional and needs to be installed with the\ndaemon:\n\n    pip install pantalaimon[ui]\n\nDo note that man pages can't be installed with pip.\n\n### macOS installation\n\nFor instance, on macOS, this means:\n\n```bash\nbrew install dbus\nperl -pi -e's#(\u003cauth\u003eEXTERNAL\u003c/auth\u003e)#\u003c!--$1--\u003e#' $(brew --prefix dbus)/share/dbus-1/session.conf\nbrew services start dbus\n# it may be necessary to restart now to get the whole OS to pick up the\n# existence of the dbus daemon\n\ngit clone https://gitlab.matrix.org/matrix-org/olm\n(cd olm; make)\ngit clone https://github.com/matrix-org/pantalaimon\n(cd pantalaimon; CFLAGS=-I../olm/include LDFLAGS=-L../olm/build/ python3 setup.py install)\n\nexport DBUS_SESSION_BUS_ADDRESS=unix:path=$(launchctl getenv DBUS_LAUNCHD_SESSION_BUS_SOCKET)\ncd pantalaimon\nDYLD_LIBRARY_PATH=../olm/build/ pantalaimon -c contrib/pantalaimon.conf\n\n# for notification center:\ngit clone https://github.com/fakechris/notification-daemon-mac-py\n# if you have django's `foundation` library installed and your filesystem\n# is case insensitive (the default) then you will need to `pip uninstall foundation`\n# or install PyObjC in a venv...\npip install PyObjC daemon glib dbus-python\ncd notification-daemon-mac-py\n./notify.py\n```\n\n### Docker\n\nAn experimental Docker image can be built for Pantalaimon, primarily for use in bots.\n\n```bash\ndocker build -t pantalaimon .\n# Create a pantalaimon.conf before running. The directory mentioned in the\n# volume below is for where Pantalaimon should dump some data.\ndocker run -it --rm -v /path/to/pantalaimon/dir:/data -p 8008:8008 pantalaimon\n```\nThe Docker image in the above example can alternatively be built straight from any branch or tag without the need to clone the repo, just by using this syntax:\n```bash\ndocker build -t pantalaimon github.com/matrix-org/pantalaimon#master\n```\n\nAn example `pantalaimon.conf` for Docker is:\n```conf\n[Default]\nLogLevel = Debug\nSSL = True\n\n[local-matrix]\nHomeserver = https://matrix.org\nListenAddress = 0.0.0.0\nListenPort = 8008\nSSL = False\nUseKeyring = False\nIgnoreVerification = True\n```\n\nUsage\n=====\n\nWhile pantalaimon is a daemon, it is meant to be run as the same user as the app it is proxying for. It won't\nverify devices for you automatically, unless configured to do so, and requires\nuser interaction to verify, ignore or blacklist devices. A more complete\ndescription of Pantalaimon can be found in the [man page](docs/man/pantalaimon.8.md).\n\nPantalaimon requires a configuration file to run. The configuration file\nspecifies one or more homeservers for pantalaimon to connect to.\n\nA minimal pantalaimon configuration looks like this:\n```dosini\n[local-matrix]\nHomeserver = https://localhost:443\nListenAddress = localhost\nListenPort = 8009\n```\n\nThe configuration file should be placed in `~/.config/pantalaimon/pantalaimon.conf`.\n\nThe full documentation for the pantalaimons configuration can be found in\nthe [man page](docs/man/pantalaimon.5.md) `pantalaimon(5)`.\n\nNow that pantalaimon is configured it can be run:\n\n    pantalaimon --log-level debug\n\nAfter running the daemon, configure your client to connect to the daemon instead\nof your homeserver. The daemon listens by default on localhost and port 8009.\n\nNote that logging in to the daemon is required to start a sync loop for a user.\nAfter that clients can connect using any valid access token for the user that\nlogged in. Multiple users per homeserver are supported.\n\nFor convenience a systemd service file is provided.\n\nTo control the daemon an interactive utility is provided in the form of\n`panctl`.\n\n`panctl` can be used to verify, blacklist or ignore devices, import or export\nsession keys, or to introspect devices of users that we share encrypted rooms\nwith.\n\n### Setup\nThis is all coming from an excellent comment that you can find [here](https://github.com/matrix-org/pantalaimon/issues/154#issuecomment-1951591191).\n\n\n\n1) Ensure you have an OS keyring installed. In my case I installed `gnome-keyring`. You may also want a GUI like `seahorse` to inspect the keyring. (pantalaimon will work without a keyring but your client will have to log in with the password every time `pantalaimon` is restarted, instead of being able to reuse the access token from the previous successful login.)\n\n2) In case you have prior attempts, clean the slate by deleting the `~/.local/share/pantalaimon` directory.\n\n3) Start `pantalaimon`.\n\n4) Connect a client to the `ListenAddress:ListenPort` you specified in `pantalaimon.conf`, eg to `127.0.0.1:8009`, using the same username and password you would've used to login to your homeserver directly.\n\n5) The login should succeed, but at this point all encrypted messages will fail to decrypt. This is fine.\n\n6) Start another client that you were already using for your encrypted chats previously. In my case this was `app.element.io`, so the rest of the steps here assume that.\n\n7) Run `panctl`. At the prompt, run `start-verification \u003cuser ID\u003e \u003cuser ID\u003e \u003cElement's device ID\u003e`. `\u003cuser ID\u003e` here is the full user ID like `@arnavion:arnavion.dev`. If you only have the one Element session, `panctl` will show you the device ID as an autocomplete hint so you don't have to look it up. If you do need to look it up, go to Element -\u003e profile icon -\u003e All Settings -\u003e Sessions, expand the \"Current session\" item, and the \"Session ID\" is the device ID.\n\n8) In Element you will see a popup \"Incoming Verification Request\". Click \"Continue\". It will change to a popup containing some emojis, and `panctl` will print the same emojis. Click the \"They match\" button. It will now change to a popup like \"Waiting for other client to confirm...\"\n\n9) In `panctl`, run `confirm-verification \u003cuser ID\u003e \u003cuser ID\u003e \u003cElement's device ID\u003e`, ie the same command as before but with `confirm-verification` instead of `start-verification`.\n\n10) At this point, if you look at all your sessions in Element (profile icon -\u003e All Settings -\u003e Sessions), you should see \"pantalaimon\" in the \"Other sessions\" list as a \"Verified\" session.\n\n11) Export the E2E room keys that Element was using via profile icon -\u003e Security \u0026 Privacy -\u003e Export E2E room keys. Pick any password and then save the file to some path.\n\n12) Back in `panctl`, run `import-keys \u003cuser ID\u003e \u003cpath of file\u003e \u003cpassword you used to encrypt the file\u003e`. After a few seconds, in the output of `pantalaimon`, you should see a log like `INFO: pantalaimon: Successfully imported keys for \u003cuser ID\u003e from \u003cpath of file\u003e`.\n\n13) Close and restart the client you had used in step 5, ie the one you want to connect to `pantalaimon`. Now, finally, you should be able to see the encrypted chats be decrypted.\n\n14) Delete the E2E room keys backup file from step 12. You don't need it any more.\n\n\n15) If in step 11 you had other unverified sessions from pantalaimon from your prior attempts, you can sign out of them too.\n\nYou will probably have to repeat steps 11-14 any time you start a new encrypted chat in Element.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fpantalaimon","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fpantalaimon","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fpantalaimon/lists"}