7 min read

Dojo Vanilla on Linux x86

Dojo Vanilla on Linux x86


In this howto I go through all the steps for installing Dojo Vanilla on your Linux X86. The installations needs an already installed Bitcoin Core and an indexer like Fulcrum. However, I also go into the points where you can install these two components via Dojo Vanilla.


Before we start with the installation we have to install docker and docker-compose on our system.

sudo apt-get update 
sudo apt-get install ca-certificates unzip curl gnupg lsb-release

Adding GPG-keys

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

Adding repo for docker

sudo echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin

Check if docker is installed correctly

docker --version

The output must look like this

Docker version 20.10.21, build baeda1f

Adding your system user to the docker group

sudo usermod -aG docker $USER

Now you have to logout and login again

Download Dojo Vanilla

cd ~/Downloads

In the next step we visit the repo from Samourai and download the latest version of Dojo Vanilla.

wget https://code.samourai.io/dojo/samourai-dojo/-/archive/v1.18.1/samourai-dojo-v1.18.1.zip

Unzip the file

unzip samourai-dojo-v1.18.1.zip -d .

Now we want to rename the unzipped folder and move it in our user home directory

mv samourai-dojo-v1.18.1 ~/Dojo


In this step we must edit some configuration files. To do so we have to change to our Dojo directory.

cd ~/Dojo/docker/my-dojo

Here we can find a directory called conf

cd conf

In this directory we can find every configuration file for Dojo Vanilla. Be careful we only want to edit the .tpl files!


nano docker-bitcoind.conf.tpl

change the RPC_USER and RPC_PASSWORD


change to


change to


We scroll a little bit further to the setting for BITCOIND. If we don't have a running Bitcoin Core installation we have to set the parameter to on, if we don't have a Bitcoin Core installation we set it to off. In this howto we don't want to use the Bitcoin Core installation from Dojo Vanilla.


change to


change the ip-address for BITCOIND




(change the 192.x.x.x to you ip-address)

Change the port




Change the parameter for ZMQ, we can find the settings in our bitcoin.conf



change to




change to


Now we save the config file with STRG + x and enter.


We can leave everyting as it is.


If we want to install the bitcoin explorer with Dojo Vanilla we set the parameter to on, otherwise to off.


In this configuration file we can configure our indexer. If you have already installed an indexer like Fulcrum or Electrum set the setting "INDEXER_INSTALL" to off. For an external Fulcrum indexer:


change to


change the ip-address




Change the port for the indexer




For a Fulcrum server we have to set the parameter for the indexer batch support to active.


Set to active


For tls


Change to tls


Now we save the config file with STRG + x and enter.


In this config file we have to change all the passwords for security reasons. You should use a password manager like KeePass or Bitwarden to generate randomized passwords.


Change to


change to


Now we save the config file with STRG + x and enter.


In this config file we set the password for our Dojo Maintenance Tool (DMT). I also recommend to use KeePass or Bitwarden for randomized passwords.


change to


Now we set the password for the login.


change to


In the last step we have to change the indexer.


change to


Save the config file with STRG + x and enter.


If we want to run whirlpool with our Dojo Vanilla installation, we have to set the following parameter to on.


change to


Save the config file with STRG + x and enter.

Info: Alternatively, we can install Whirlpool manually. This gives us the option to mix directly to an external XPUB after X rounds. You can find the steps below.

Dojo Vanilla installation

Now we install Dojo Vanilla with our new configuration.

./dojo.sh install

We confirm with "y"

Our Dojo is ready as soon as we see "INFO Tracker: Processing active Mempool". It can take a little wile.

Alternative Whirlpool installation

If we want to install Whirlpool manually, we go to https://code.samourai.io/whirlpool/whirlpool-client-cli/-/releases where we can find the latest Whirlpool CLI version.

The advantage of a separate installation would be the easy setup for the Mix-to-XPUB feature.

Before we can start, we need to install Java. On Ubuntu we just type java in the terminal to see the possible options.

sudo apt install openjdk-18-jre-headless

Now we create a directory for Whirlpool

mkdir ~/Whirlpool

We change into the directory

cd ~/Whirlpool

In the next step we download the latest version from the Samourai Whirlpool CLI repo.

wget https://code.samourai.io/whirlpool/whirlpool-client-cli/uploads/63621e145967f536a562851853bd0990/whirlpool-client-cli-0.10.16-run.jar

Create a service file for our Whirlpool

sudo nano /etc/systemd/system/whirlpool.service



ExecStart=/usr/bin/java -jar whirlpool-client-cli-0.10.16-run.jar --server=mainnet --tor --auto-mix --mixs-target=0 --listen


Save the file with STRG + x and enter.

Enable the service

sudo systemctl enable whirlpool

We don't want to start the service now!

Info: If there are any Whirlpool CLI updates, we have to adjust the line with ExecStart in the service file!

Installation Whirlpool GUI

From the Samourai website we want to download the current version of Whirlpool GUI and install it.


All installation steps are now complete. If you want to know all the commands of dojo.sh, you can find them on the Samourai repo.


cd ~/Dojo/docker/my-dojo

Stop Dojo

./dojo.sh stop

Start the upgrade

./dojo.sh upgrade

Connect our Samourai Wallet with Dojo and Whirlpool

Visit Dojo Maintenance Tool

With the following command we get the onion-address for our DMT

./dojo.sh onion

Now we start the Tor browser and visit the onion-address. The password is the one from our docker-node-tpl.conf (NODE_ADMIN_KEY).

Installation Samourai Wallet

We download the Samourai Wallet from the website https://samouraiwallet.com. It can be found under "Download". There are several options. Either a direct download of the APK file, via F-Droid or Google Play.

We start the wallet and select MAINNET or TESTNET depending on our Dojo installation. Then we click on "Get Started". Now we select the directory where the wallet backups should be stored. After that we choose if we want to enable Tor. We need Tor for the connection for Dojo. Then we click on Dojo and scan the QR code that we find in the Dojo Maintenance Tool under Tools - Pairing. If everything is okay, the Dojo status should say "Connected".

Now we need to set a passphrase, it has to be SECURE! We write down the 12 words we need in a recovery along with the passphrase. If you want a recovery sheet, you can find it here.

The wallet is now fully installed and set up.

Connect our wallet with our Whirlpool CLI

java -jar whirlpool-client-cli-0.10.16-run.jar --init

INPUT REQUIRED for Pairing Payload - here we need to enter our Pairing Payload, which we can find in our Samourai Wallet under Settings -> Transactions -> Experimental. We copy and paste it into the query.

INPUT REQUIRED for passphrase - here we enter our passphrase of the wallet.

Now we start Whirlpool

sudo systemctl start whirlpool

Check if everything is okay

sudo systemctl status whirlpool


If we want to mix to an external XPUB, we have to configure it. We do this with the --set-external-xpub parameter.

We run the command

java -jar whirlpool-client-cli-0.10.16-run.jar --set-external-xpub

In the query "External BIP84 XPub/ZPub" we enter the XPUB.

In the next query "Chain?(0)" (default for m/84'/0') we enter 0.

In the next query "Mixs?(>0)>" we enter the number of mix rounds before the mixed UTXOs are sent to cold storage.

INPUT REQUIRED Continue y/n - here we check 3 addresses that were calculated from our ZPUB. We should check them with the wallet from our cold storage. If they match, we confirm with y.

With these steps everything is now set up in the whirlpool.cli.properties file. We can start and stop Whirlpool normally via our Whirlpool Service.

Connect Whirlpool GUI - Whirlpool CLI

To hook up Whirlpool GUI with Whirlpool CLI we need the ip-address of Whirlpool CLI and an apiKey.

We start Whirlpool GUI and click on Advanced: remote CLI. In the field we set the ip-address of your Dojo server. We leave the port 8899 as it is.


In the Whirlpool directory we find a file called "whirlpool-cli-config.properties". In this file we will find a setting called "cli-apiKey". This is the api key we need for the connection.

cat ~/Whirlpool/whirlpool-cli-config.properties

No we click on "Connect"

Finally we will be asked for the passphrase, after entering it everything is connected.

You can generate receiving addresses with Whirlpool GUI under Deposit, which means that you do not have to open the Samourai wallet. Whirlpool GUI does not have to be running during the mix.

SCODE: If Samourai offers a discount on the fees for mixes, we can enter it under "Configuration".

Under System - Reset you can reset everything.

All information can be found on the Samourai website.

If this article was helpful for you, please consider a donation to the author.