Murmeli - Robot setup

This page explains how to setup a new robot relay for the friend-to-friend messaging system Murmeli. Having a robot isn't necessary to use Murmeli, but having at least one robot in your friend network brings greater convenience. The robot can stay online, like a voicemail service, even when your main Murmeli client goes offline. In this way, you can receive a message from your friend even if you weren't ever online at the same time.


The robot can be any Murmeli-capable hardware but it is intended to be left online for most or all of the time, so it would be an advantage if it were a lower-power device like for example a raspberry pi. Also the robot doesn't really need a keyboard or screen, so it could be a very minimal pi such as a "Pi Zero W". One example variety of such a device is a "Scrollbot" from Pimoroni, which also offers an LED matrix in a funny orange robot head. But you could also use any pi in a suitable enclosure.

The robot also needs internet connectivity, so you'd be looking at either an ethernet connection or built-in Wifi. And the power can come over regular USB, either from a USB-A socket or from some kind of mains power supply.


Depending on which hardware you are using, maybe not all of these steps will be necessary.

Step 0 - hardware

For a regular Pi, you'll need to somehow get the Pi, an SD or micro-SD card, perhaps an enclosure, and the necessary cables for ethernet and power. Temporary access to a USB keyboard and a HDMI screen will probably be useful just for the setup.

For a Scrollbot, you'll need to get some kind of Scrollbot kit from Pimoroni which includes a Pi Zero W. Then normally you'll need to do a little bit of soldering, to attach the headers to the pi and to the LED matrix. The assembly of the robot head is very straightforward. You'll also need a micro-SD card, and again temporary use of a USB keyboard and HDMI screen might be useful.

Step 1 - Raspbian

Next you'll need some kind of operating system. If you've got some kind of Raspberry Pi (Zero, Zero W, 1, 2, 3, 4) this will probably be 'Raspbian Buster (stable)', and if you're using a headless Pi without a screen (like a Scrollbot) then you can use the smller, reduced image 'Raspbian Buster Lite'.

The Raspbian images can be downloaded from (for example, using the torrent) and then just follow the install instructions. These consist of verifying the zip (for example, using sha256), unzipping it (for example, using unzip) and then transferring to the micro-SD (for example, using dd).

If you're using another kind of hardware (like a regular low-power PC) then you can use another kind of Linux (for example, Debian) or of course another OS of your choice.

Step 2 - Configuration

If you're using Wifi, you'll need to configure this with the network name and password so that the robot can access the internet. This is quite conveniently done using a wpa-supplicant.conf file transferred onto the SD card. Now you can boot the pi for the first time from the card, at which point the partitions will be resized.

Now is a good time to set the hostname (for example, using sudo raspi-config) and also to enable SSH (again using sudo raspi-config). Also recommended is to change the user password, and optionally to place a public key (from ssh-keygen) on the pi in order to use ssh and sftp without a password.

Step 3 - Software

Even though the Raspbian image has only just been installed, it's already time for a software upgrade to get the latest packages since the Raspbian image was built. This is best done with sudo apt update and sudo apt upgrade.

Now you can add the required packages for Murmeli, which can be installed with sudo apt install python3 tor python3-socks gnupg python3-gnupg python3-pil. For the Scrollbot you'll also need the scrollphathd code from pimoroni, which comes in the form of a large bash script. If you're not running a Scrollbot but you're getting errors about scrollphathd and i2c, you may want to see if python3-scrollphathd is installed and if necessary, remove it.

Finally you'll need the Murmeli code, either downloaded directly to the Pi or transferred using sftp.

Step 4 - Key export

The next step takes place on your real, GUI-enabled Murmeli client. First, either run start_murmeli and go through the GUI setup wizard, or run setup_murmeli and go through the console prompts. Either way, a keypair will be generated on your main client.

Then start Murmeli on the main client, go to your own details page, go to "Edit" your own details, and then select "Add Robot". This will give an option to "Export" your public key to a file in your data directory.

Finally, copy this public key file (for example, using sftp) into the robot's data directory.

Step 5 - Robot setup

In a terminal on the robot, run export GPG_TTY=$(tty) before running the setup, to allow GPG to ask for the password.

In the same terminal on the robot, run setup_murmeli and choose the language and data directory. Select to setup a "robot system" and import the public key file exported in step 4. Note the Murmeli Id generated by the robot, as you'll need to give this to your main client in the next step.

On the robot, run start_robot and Murmeli should start. On a Scrollbot, the LEDs should indicate that it's now running.

Step 6 - Connection

On your main client, now enter the Murmeli Id of the robot into the "Add robot" panel and press "Send". This lets your main client send a contact request to your robot, and because the robot knows your public key, it can easily verify your request. When the request is received by the robot, this message receipt will be indicated on the Scrollbot's LEDs.

The robot will verify the signature and if correct it will respond with a contact accept request. This goes back to your main client, which will complete the configuration on its side. Now your robot's status (such as "Enabled, online") will be shown on your main client's details page.

Parrot setup

The robot concept has recently been extended to include an alternative unattended Murmeli client called a 'Parrot'. This behaves a little like a robot, in that it can forward messages automatically, but it's only intended for test purposes. Instead of being an invisible helper whose job is to reduce latency between humans, a parrot is a noisy conversation partner, like an echo service. It pretends to be a real Murmeli user, and automatically accepts any contact requests sent to it. It can also receive regular messages (which are ignored by robots), and automatically replies to them too, repeating back to you what you said.

The purpose of a parrot, as well as to make testing easier, is to make it possible for anyone anywhere to contact the Murmeli developers through Murmeli. Simply send a contact request to the parrot, immediately become an untrusted friend, and then send any message you like to the parrot. Because the parrot has an 'owner', anything received by the parrot can be read by its owners too. So if you want to say hello, report bugs, make feature requests, ask questions or give feedback, then the parrot will be listening.

Some testing is ongoing using a Raspberry Pi, and once this is complete we'll publish the parrot's Murmeli id here.

If you want your own parrot, just follow the instructions above to setup a robot, but select the parrot system type. Then start the client with python3 parrot


Introduction // Development // Beschreibung // Threats // Questions & answers // Message types // Message sequences // Robot setup