Samourai Dojo

The edge of privacy features

There is no greater solitude than that of a samoura├», unless it is that of the tiger in the jungle…perhaps…

A manual for running Samourai Dojo with an external full node. Source code is available.


Dojo sits on top of a full node and gives it some privacy super powers. It is fairly complex and definitely out on the edge of new tech. Like, it has its own big index over the blockchain. I appreciate it a lot, but am personally focusing on the Lightning Network to help address bitcoin fungibility concerns. Sparrow wallet is a good way to support Samourai/Dojo without having to run a full node’s worth of complexity.

Why an external full node?

I am running a full node on my bare metal box. I understand it and am not quite ready to migrate it to Dojo’s docker-compose managed image. I like the idea of modularity and I have other services which depend on the full node. Dojo can expose it’s managed full node, but that is a project for another day.


Dojo has some advanced docs on running an external full node, but still took me a bit to figure out.

The complexities boil down to full node configurations (e.g. /etc/bitcoin/bitcoin.conf) to make sure the Dojo containers can talk to the node. The Dojo containers are on their own “bridged” network, so its not as simple as always putting


real life working configuration with the password changed

  1. rpcallowip
  1. rpcbind
  1. zmqpubhashblock and zmqpubrawtx

These network settings are more open than the standard and extra precautions should be taken in router and firewall settings to make sure access is not granted to things which shouldn’t have it (like the internet).

System manager

I am using Systemd to control starting and stopping Dojo.

Description=Samourai Dojo
# Using external full node
After=bitcoind.service docker.service

# the dojo script used the -d parameter in docker-compose
ExecStart=/usr/lib/dojo/docker/my-dojo/dojo.sh start
ExecStop=/usr/lib/dojo/docker/my-dojo/dojo.sh stop


The dojo docker-compose processes appear as whatever user has UUID 1001 on the host system when viewing from the host (e.g. running ps aux). This is a docker quirk and I am not sure the best pattern to deal with it other than creating a matching user on the host system.


Make sure to perform upgrades with start/stop through the script dojo.sh, not docker-compose directly. The script handles a few complexities.


The Samourai coinjoin implementation can be run directly from the mobile app, but to get full benefits of it running 24/7 it has to be on an always connect server. Dojo supports an “Remote CLI backed GUI” option that allows clients to connect to its whirlpool instance. Still need the Samourai wallet android app that whirlpool CLI links to and manages (must be some private key passing going on).


The most up-to-date version of whirlpool GUI might not necessarily work with the whirlpool CLI being run by Dojo. For instance, Dojo 1.9 does not work with GUI 0.10.3.

So while there are some GUI packages in the AUR, might be easier to grab a specific version based on the Dojo version running. They publish AppImage artifacts that can easily be dropped in ~/.local/bin.


Whirlpool first needs to be enabled on Dojo. Edit conf/docker-whirlpool.conf and set WHIRLPOOL_INSTALL to on. This requires a dojo.sh upgrade to enable some downstream settings like nginx configurations.


Connect to the running CLI with the GUI. The input is pretty particular and isn’t able to tell you what you got wrong if you type something in wrong. For the tor proxy, be sure to use the right port (9150 if hopping on the browser’s tunnel).

For the URL use the form: http://<ONION_ADDRESS>. Notice the http not https.

If still unable to connect, bounce the Dojo instance with dojo.sh restart. Hopefully that does the trick cause my experience ends here.