The OnionBalance software allows for Tor hidden service requests to be distributed across multiple backend Tor instances. OnionBalance provides load-balancing while also making onion services more resilient and reliable by eliminating single points-of-failure.


OnionBalance is under active development and new features are being added regularly:

  • Load balancing between up to 60 backend hidden services
  • Storage of the hidden service private key separate to the hidden service hosts


The OnionBalance ::ref::tutorial describes the deployment of an onion service with multiple backed Tor instances and web servers. The following is a minimal quickstart guide for a new installation.

Assuming there is no previous configuration in /etc/onionbalance:

$ sudo apt-get install onionbalance
$ onionbalance-config
$ sudo cp ./config/master/*.key /etc/onionbalance/
$ sudo cp ./config/master/config.yaml /etc/onionbalance/
$ sudo chown onionbalance:onionbalance /etc/onionbalance/*.key

Restart OnionBalance to reload the configuration files.

$ sudo service onionbalance restart

Check the logs. The following warnings are expected: “Error generating descriptor: No introduction points for service ...”

$ sudo tail -f /var/log/onionbalance/log

Copy the instance_torrc and private_key files from each of the directories named ./config/, srv1, srv2, ... to each of the Tor servers providing the Onion Services.

Configure and start the instance services. The onion service managed by OnionBalance should be ready within 10 minutes.