Morpheus is a platform-agnostic end-to-end encryption/decryption software for Instant Messaging (IM) platforms.

Please help yourself to the poster here, and the paper here.

If you need set-up instructions, please follow the how-to.


This page helps you set up your Morpheus installation in order to encrypt and decrypt messages securely over any instant messaging platform.

If you are in need of help for a specific scenario, please refer to the Table of Contents.

If your scenario is not in the table of contents, please do not hesitate to contact me.

I will be happy to help in case of any setup issues.


Please contact me if you have any questions.

Table of Contents

  1. Installing Morpheus
  2. Building the Extension
    1. Firefox
    2. Chrome
  3. Setting up Icelos
    1. Basic Docker Setup
    2. Advanced Setup
  4. Setting up PGP
  5. Exchanging Keys Securely
  6. Frequently Asked Questions
    1. Morpheus encountered an unexpected error
      1. Connection refused to Icelos on port XXXX
      2. Missing host permission for the tab
    2. I have received an encrypted message.
      1. Decrypting Using Morpheus
      2. Decrypting Manually

Installing Morpheus

In order to install Morpheus, you will need to build the browser extension and set up Icelos.

You will also need a working PGP setup.

Building the Extension

This section describes the browser extension. If you already have Morpheus installed in your browser, please see Setting up Icelos.

You can install the browser extension as follows:

Go to the cloned Morpheus repository.

Open folder `morpheus`.

Run `make` in this directory. This creates a .zip file that you can open in your browser.

Open up your browser, and follow the steps for Chrome or Firefox.


Create a new tab, and type in `about:addons` to the address bar.

This should take you to the "Manage Your Extensions" page.

You could also press Ctrl+Shift+A or navigate to "Addons" in the Firefox menu.

On the "Manage Your Extensions" page, click the cogwheel icon on the top right corner.

A drop down menu appears.

Click on the item "Debug Add-ons".

Do NOT click on "Install Add-on From File" as this does not currently work.

After clicking "Debug Add-ons", you should see a menu for Temporary Extensions.

Click "Load Temporary Add-on" on the top right corner.

Navigate to the zip file you created under Building the extension, and open it.

Morpheus should now be installed in your browser!


Create a new tab, and type in `about:extensions` or `chrome:extensions` to the address bar.

This should take you to the "Extensions" page.

You could also navigate to "Extensions" in Chrome settings.

Enable "Developer Mode" on the top right corner.

This will display an additional menu on the top left.

Click "Load unpacked" in the top left menu.

Navigate to the extension folder you created under Building the extension, and open the folder.

Morpheus should now be installed in your browser!

Setting up Icelos

Basic Docker Setup

The easiest way to set up Icelos is to install Docker on your computer.

You can then build the Dockerfile by doing as follows:

Go to the cloned Morpheus repository.

Run `docker-compose up` in this directory.

Icelos will start running on the specified port.

Advanced Setup

If your PGP setup is more elaborate, you can also have Icelos run directly on the host machine and connect to GPG.

This is usually required if your PGP setup greatly varies from the out-of-the-box setup, and/or if you're using smartcards or similar.

You should have Go and Make installed.

Simply go to the cloned Morpheus repository, open the folder called `icelos`, and build the binary using `make`.

Afterwards, you can run Icelos directly any time you need to use Morpheus, or keep it running using the provided Systemd daemon.

Setting up PGP

Morpheus uses GPG to encrypt and decrypt PGP messages.

There are many great resources online for GPG, for example you can follow this tutorial to get started.

The most important point is that you should never ever share your private key with anyone.

Nobody should be telling you to use a private key they generated - this is very unsecure.

Once you have GPG installed, you should generate a public-private key pair and keep the private key very private.

Other people will use your public key to encrypt messages to you. In order to tell people about your public key, you need to exchange the keys securely.

Once you start receiving messages encrypted with your public key, you can then use your private key to decrypt them.

For more information about the process, you can read this article.

Exchanging Keys Securely

This is something Morpheus cannot do due to the laws of cryptography.

If you want to exchange keys with someone, you should do that over a secure channel, or off-line.

The best way to securely exchange keys is to meet in person. This eliminates any man-in-the-middle attacks or impersonation attempts.

You can read more about secure key exchange here.

Frequently Asked Questions

Morpheus encountered an unexpected error

For error messages, hover your mouse over the error icon ⚠️ for more information.

Connection refused to Icelos on port XXXX

This means that Morpheus is failing to find Icelos that it requires to encrypt/decrypt PGP messages.

Please revise the steps in Setting up Icelos to resolve the issue, paying close attention to the port numbers.

If the port number for Morpheus (1234) is not the same as the port number of Icelos (1234), then Morpheus will not be able to find Icelos.

If you have done all the steps and this is still not working, please contact me.

Missing host permission for the tab

This means that Morpheus cannot encrypt or decrypt messages on the current tab.

Morpheus may still work on other tabs, but there are some tabs (such as the extensions page) that cannot be modified by Morpheus.

If you are having trouble due to this error, please contact me and I will be happy to assist.

I have received an encrypted message.

The message should look something akin to this.

In order to decrypt a message encrypted with Morpheus, you don't need Morpheus (although it will make your life easier).

Follow the sections below depending on whether you want to decrypt manually, or using Morpheus.

Decrypting Using Morpheus

If you do not have Morpheus installed, refer to Installing Morpheus first.

Once you have installed Morpheus, you should be able to decrypt any PGP or Morpheus messages automatically, or by pressing a lock icon next to the message.

If you get decryption errors, refer to the FAQ.

Decrypting Manually

Morpheus messages are PGP encrypted. They follow a slightly different format due to format limitation of some chat platforms.

If you do not have an active PGP setup, then you should be suspicious - the message is probably not encrypted for you.

In order to set up PGP, please refer to Setting up PGP, and afterwards ask the sender to re-send their message using your public key.

The only difference is in the start and end tokens of the messages.

Morpheus messages start with Encrypted:[ and end with a single].

The PGP data lays in the middle of these two tokens.

You can start by copying and pasting the message into your favourite text editor.

Move the start and end tokens on their own lines so you won't accidentally chop off any important data.

Then, replace the start token Encrypted:[ with -----BEGIN PGP MESSAGE-----.

Replace the end token ] with -----END PGP MESSAGE-----.

Take care as PGP is very particular about the format of these tokens.

That's it, you now have a valid PGP message!

You can now, depending on your PGP setup, decrypt this message.

Below is a command-line example.

$ gpg --decrypt message.txt gpg: encrypted with 2048-bit RSA key, created 2020-02-04 👍

It is, of course, quite cumbersome to do this for every message that you receive.

If you end up doing this a lot you might want to look into installing Morpheus.