Setting up a local BitMessage Network using Docker

BitMessage is a blockchain-inspired P2P messaging platform to allow users to anonymously exchange or broadcast encrypted messages.  The platform is distributed, decentralized and trustless.

This blog post will show how you can setup a local BitMessage network so you can explore and experiment with the code.

You can checkout the code for PyBitMessage (the python reference client) here, and you can download my scripts to setup your own local BitMessage environment here.

There are instructions to build and run the Docker image in the README file in GitHub, I won’t repeat everything here but I’ll explain some of the high level concepts.

Unlike BitCoin, BitMessage doesn’t come with a “development” network right out-of-the-box, so you have to take a few steps to roll your own.  After checking out the PyBitMessage source code, you need to edit the following file:


This script loads some “well known” nodes on the BitMessage network – you have to comment these out so that you don’t connect to the production network!  I comment out all the real “well-known” nodes and add one of my own – the IP and port number of my local BitMessage instance.

Second you have to update some of the configuration files.  The updates are checked into my GitHub project above, and are deployed for each Docker instance that you run.

First, keys.dat contains a configuration to specify the type of automatic “DNS lookup” BitMessage will use to find nodes to connect to – you need to disable this for a local network.

Second, keys.dat contains a port number that each instance will listen on – you need to configure a unique port number for each instance (so they don’t conflict).

Lastly, since PyBitMessage is a GUI application, you need to ensure that each Docker container can connect to the host’s X server – I disable all X security using “xhost +”, but since this is a security hole you may want to setup finer grained security.

(Note that I run this environment inside a VM, and when testing the local BitMessage network I disable all network connections to the VM.  This compensates for the X security issue above, and also ensures that my local BitMessage network can absolutely NOT connect to the production network.

Once you have built the base Docker image and started up the instances, you can generate Identities and send messages between each of the clients.  See the README file in GitHub for detailed instructions.

It’s pretty simple!  If you have any questions please feel free to email me at