Installation

There are three different ways to install TorBox on a Raspberry Pi 3 (Model B / Model B+) or a Raspberry Pi 4 Model B running Raspberry Pi OS Lite:

There are additional installation scripts for other systems, which might run on other hardware platforms, too. However, TorBox’s implementation on other systems and hardware is experimental because we do not have the resources to check all details on all different installations. You can help us to with reporting errors back to us.

• • •

Using our image file on a Raspberry Pi (recommended!)

This is the recommended and probably easiest way to install TorBox on a Raspberry Pi:

  1. Download the latest TorBox image file (TorBox v.0.5.0 based on Raspberry Pi OS “Bullseye” Lite with the Linux Kernel 5.10.63 and Tor version 0.4.6.9; 985MB) and verify the integrity of the downloaded file.
  2. Transfer the downloaded image file on an SD Card, for example, with Etcher. TorBox needs at least a 8 GB SD Card.
  3. Put the SD Card into your Raspberry Pi, link it with an Internet router using an Ethernet cable, or place an USB WiFi adapter in one of the USB ports to use an existing WiFi. Afterwards, start the Raspberry Pi. During the start, the system on the SD card automatically expands over the entire free partition – user interaction, screen, and peripherals are not required yet.
  4. After 2-3 minutes, when the green LED stops to flicker, connect your client to the new WiFi “TorBox050” (password: CHANGE-IT).
  5. Login to the TorBox by using a SSH client (192.168.42.1 on a WiFi client or 192.168.43.1 on a cable client) or a web browser (https://192.168.42.1:9000 on a WiFi client or https://192.168.43.1:9000 on a cable client; for a connection via cable, see here; username: torbox / password: CHANGE-IT).
  6. After seeing a welcome screen and answering some initial questions during the first start-up, you should see the TorBox Main Menu. Choose the preferred connection setup and change the default passwords as soon as possible (the associated entries are placed in the configuration sub-menu).

We recommend running TorBox on a Raspberry Pi 3 (Model B / Model B+) or a Raspberry Pi 4 Model B under Raspberry Pi OS “Buster” Lite.

• • •

Using our installation script on a Raspberry Pi with Raspberry Pi OS Lite

This is probably the most efficient way to install TorBox. In addition, with that method, you will have the latest version of the base system and the TorBox menu and don’t have to wait for the next release of the image file.

  1. Download the latest version of the Raspberry Pi OS Lite (about 442 MB)
  2. Transfer the downloaded Raspberry Pi OS Lite image on an SD Card; for example, with Etcher. TorBox needs at least a 8 GB SD Card.
  3. Log into your newly set up system and, if needed, configure it with “sudo raspi-config”.
    Important
    – You need to have a stable Internet connection. This is necessary to ensure that the
    installation script runs smoothly.
  4. Download and run the script:
cd
wget https://raw.githubusercontent.com/radio24/TorBox/master/install/run_install.sh
chmod a+x run_install.sh  
./run_install.sh 

The installation script supports the following options:

Syntax : run_install.sh [-h|--help] [--select-tor] [--select-branch branch_name] [--step_by_step]
Options: -h, --help     : Shows this help screen ;-)
         --select-tor   : Let select a specific tor version (default: newest stable version)
         --select-fork fork_owner_name
			            : Let select a specific fork from a GitHub user (fork_owner_name)
         --select-branch branch_name
                        : Let select a specific TorBox branch (default: master)
         --step_by_step : Executes the installation step by step
  1. Restart the system; after 2-3 minutes, when the green LED stops to flicker, connect your client to the new WiFi “TorBox042” (password: CHANGE-IT).
  2. Login to the TorBox by using a SSH client (192.168.42.1 on a WiFi client or 192.168.43.1 on a cable client) or a web browser (https://192.168.42.1:9000 on a WiFi client or https://192.168.43.1:9000 on a cable client; for a connection via cable, see here; username: torbox / password: CHANGE-IT). TorBox will ask if it is necessary to activate OBFS4 bridges for hiding the use of the Tor network. The integrated OBFS4 bridges should help with that, although patience is necessary because that process could easily take 5 minutes to be successful. However, if you cannot connect to the Tor network yet, don’t panic – your selection is saved, and you can choose safely entry 5-10 in the Main Menu (we will improve the usability with the next version). This is only necessary during the first start after flashing the TorBox image on the SD cards. However, you can change your decision and configure the use of bridges later in the Countermeasure sub-menu.
  3. Finally, you should see the TorBox Main Menu. Choose the preferred connection setup and change the default passwords as soon as possible (the associated entries are placed in the configuration sub-menu).

• • •

Installation from scratch on a Raspberry Pi with Raspberry Pi OS Lite

This is probably the safest, however, also the most conplicated and time-consuming way to install TorBox. Technically, it doesn’t differ from the installation with the installation script — the only difference is that you write the necessary configuration files by hand.
Form more information, go to our detailed manual.

• • •

EXPERIMENTAL: Using scripts for other systems and hardware platforms
Operating SystemOS imageScriptTested onRemarks & Restrictions
Debian 11 (Bullseye)Raspberry Pi Debian Imagesrun_install_on_debian.shRaspberry Pi 4➔ see Footnotes 1
Ubuntu Server 20.04.3 LTS / 21.10 Ubuntu on a Raspberry Pirun_install_on_ubuntu.shRaspberry Pi 4➔ see Footnotes 2

To install TorBox on another system or hardware, download the OS image, transfer it to an SD Card, log into your newly set up system, download and run the script with the following command:

cd 
wget https://raw.githubusercontent.com/radio24/TorBox/master/install/<script>
chmod a+x <script>
./<script>

The installation script supports the following options:

Syntax : run_install_on_<OS>.sh [-h|--help] [--select-tor] [--select-branch branch_name] [--step_by_step]
Options: -h, --help     : Shows this help screen ;-)
         --select-tor   : Let select a specific tor version (default: newest stable version)
         --select-fork fork_owner_name
			            : Let select a specific fork from a GitHub user (fork_owner_name)
         --select-branch branch_name
                        : Let select a specific TorBox branch (default: master)
         --step_by_step : Executes the installation step by step
  • Restart the system; after 2-3 minutes, when the green LED stops to flicker, connect your client to the new WiFi “TorBox042” (password: CHANGE-IT).Login to the TorBox by using a SSH client (192.168.42.1 on a WiFi client or 192.168.43.1 on a cable client) or a web browser (https://192.168.42.1:9000 on a WiFi client or https://192.168.43.1:9000 on a cable client; for a connection via cable, see here; username: torbox / password: CHANGE-IT). TorBox will ask if it is necessary to activate OBFS4 bridges for hiding the use of the Tor network. The integrated OBFS4 bridges should help with that, although patience is necessary because that process could easily take 5 minutes to be successful. However, if you cannot connect to the Tor network yet, don’t panic – your selection is saved, and you can choose safely entry 5-10 in the Main Menu (we will improve the usability with the next version). This is only necessary during the first start after flashing the TorBox image on the SD cards. However, you can change your decision and configure the use of bridges later in the Countermeasure sub-menu.
  • Finally, you should see the TorBox Main Menu. Choose the preferred connection setup and change the default passwords as soon as possible (the associated entries are placed in the configuration sub-menu).
Footnotes to Remarks & Restrictions

Footnotes 1 regarding Debian 11 (Bullseye):

  • We tested it only on a Raspberry Pi 4, but it should also work on a Raspberry Pi 3B+ using the correct image.
  • Debian 11 (Bullseye) on a Raspberry Pi may more cumbersome than the Raspberry Pi OS. Especially booting up and (re-)configuring the network may need noticeable more time.
  • After installing TorBox and starting up th freshly Debian 11 (Bullseye) system, you might wait one or two minutes until you can log in.
  • For some unknown reason, Rasperry LED’s are off by default, but are very easy to turn on via the /sys pseudo-filesystem. See here, how to turn the LED’s on.
  • Some USB WiFi adapters and hat/shields may not work.

Footnotes 2 regarding Ubuntu Server 20.04.3 LTS / 21.10:

  • Ubuntu’s image file and also the space used by the system after the installation takes about 30% more space than Debian or Raspberry Pi OS.
  • After starting a freshly installed system, you might wait one or two minutes until you can log in with the name “ubuntu” and the password: “ubuntu”.
  • It seems that Ubuntu’s support for network drivers is better than on Debian or Raspberry Pi OS.
  • Especially at the beginning, after a freshly installed TorBox, sometimes, the user is asked to type in his password.