Installation

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

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:

Download the latest TorBox image file (TorBox v.0.5.3 based on Raspberry Pi OS “Bookworm” lite 64bit with the Linux Kernel 6.1.21 and Tor version 0.4.8.10 with obfs4proxy version 0.0.14 and Snowflake 2.8.0; ~1.25 GB) and verify the integrity of the downloaded file.
Transfer the downloaded image file on an SD Card, for example, with Etcher. TorBox needs at least a 8 GB SD Card.
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.
After 2-3 minutes, when the green LED stops to flicker, connect your client to the new WiFi “TorBox053” (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 (http://192.168.42.1 on a WiFi client or http://192.168.43.1 on a cable client; for a connection via cable, see here; username: torbox / password: CHANGE-IT).
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 “Bullseye” lite 64bit. TorBox should also work on a new Raspberry Pi 5, but we couldn’t verify this yet. For older (32-bit only) hardware and operating systems, please check our alternative installation scripts or build it from scratch using our manual.

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.

Download the latest version of Raspberry Pi OS Lite (64-bit) or use the Raspberry Pi Imager and choose, under Operating System, Raspberry Pi OS (other), the Raspberry Pi OS Lite (64-bit) image. With the Raspberry Pi Imager, you can also setup a Hostname, SSH, WiFi AP, username (use torbox), and your preferred password for a headless installation.
If you don’t use the Raspberry Pi Imager, then 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.
If asked, create a user “torbox” and remember the chosen password for later use.
Under Debian, log into your server as root. With Ubuntu, log into your server as a user (for example ubuntu or torbox). Optionally, localize your installation with raspi-config.
Ensure stable Internet connectivity, download and execute our installation script (for options, use --help):

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] [--randomize_hostname] [--select-tor] [--select-fork] [--select-branch branch_name] [--step_by_step]
Options: -h, --help     : Shows this help screen ;-)
         --randomize_hostname
                        : Randomizes the hostname to prevent ISPs to see the default
         --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 “TorBox053” (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 (http://192.168.42.1:9000 on a WiFi client or http://192.168.43.1:9000 on a cable client; for a connection via cable, see here; username: torbox / and your chosen password (if no login/pasword was asked, try torbox/ CHANGE-IT).
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.

Using scripts for other systems and hardware platforms

We tested the installation only on a Raspberry Pi 4, but it should also work on an older Raspberry Pi if using the correct image.

Operating System	OS image	Script	Remarks & Restrictions
Debian 12 (Bookworm)	Raspberry Pi Debian Images	run_install_on_debian.sh	➔ see Footnotes 1
Ubuntu Server 22.04.2 LTS Ubuntu Server 23.04	Ubuntu on a Raspberry Pi or use the Raspberry Pi Imager	run_install_on_ubuntu.sh	➔ see Footnotes 2

To install TorBox on another system or hardware, download the OS image, transfer it to an SD Card. Under Debian, log into your server as root. With Ubuntu, log into your server as a user (for example ubuntu or create the user torbox). Then download and start the installation script:

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] [--randomize_hostname] [--select-tor] [--select-fork] [--select-branch branch_name] [--step_by_step]
Options: -h, --help     : Shows this help screen ;-)
         --randomize_hostname
                        : Randomizes the hostname to prevent ISPs to see the default
         --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 “TorBox053” (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 (http://192.168.42.1 on a WiFi client or http://192.168.43.1 on a cable client; for a connection via cable, see here; username: torbox / password: CHANGE-IT or your chosen password).
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).

Footnotes to Remarks & Restrictions

Footnotes 1 regarding Debian 12 (Bookworm):

Before you can use wget, you have to prepare the Debian system:
.
- Make sure that you are connected with the Internet (if necessary, see Addendum: How to connect to a wireless network from the CLI?).
- Set the correct date and time (UTC) with date -s "YYYY-MM-DDHH:MM"
- Update the system with apt-get -y update
- Install wget with apt-get -y install wget
After installing TorBox and starting up the freshly Debian 11 (Bullseye) system, you might wait one or two minutes until you can log in.
Debian on a Raspberry Pi may tend to have more problems with wireless adapters and their drivers than the Raspberry Pi OS.

Footnotes 2 regarding Ubuntu Server 22.04.2 LTS and Ubuntu Server 23.04:

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. However, because of the unpredictability of the Predictable Network Interface Names, we may have to disable that feature before we can connect to a network. You can do that with the following command: sudo ln -s /dev/null /etc/udev/rules.d/80-net-setup-link.rules and restart the system again.
Especially at the beginning, after a freshly installed TorBox, sometimes, the user is asked to type in his password.
Sometimes Ubuntu has some compatibility issues with the SSH terminal.

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

This is probably the safest, however, also the most complicated 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.

Addendum: How to connect to a wireless network from the CLI?

The easiest and most reliable way to install TorBox using one of the installation scripts is to connect the Raspberry Pi to Ethernet. A little bit more complicated is using the onboard wireless chip, especially because we don’t want to install and start a Graphical User Interface. Because not everyone has the right procedure in mind how to connect a wireless network on the Command Line Interface (CLI), we will guide you through.

We asume that you logged in as root. If this is not the case, you may use sudo in front of the commands.
Unblock the wireless interfaces with rfkill unblock wlan.
Stop an already running wpa_supplicant with systemctl stop wpa_supplicant.
Stop NetworkManager: sudo systemctl stop NetworkManager
Prepare the wireless interface: ip link set dev wlan0 up
Find wireless networks and note down the name (SSID): iw wlan0 scan | grep SSID:
Build the wpa_supplicant.conf (<SSID> is the name of the wireless network to connect, <wifi-password> the password of <SSID>): wpa_passphrase <SSID> <wifi-password> | tee -a /etc/wpa_supplicant/wpa_supplicant.conf
Connect to the wireless network: wpa_supplicant -B -c /etc/wpa_supplicant/wpa_supplicant.conf -i wlan0
Start dhclient to get an IP: dhclient wlan0

John Doe on Test TorBox mini and contribute with feedback: “If you use Debian on a Banana Pi, then you can install TorBox with our Debian installation Script. Please be…” Apr 14, 20:33
Jose on Test TorBox mini and contribute with feedback: “any plans on doing this with a banana pi?” Apr 14, 19:00
John Doe on FAQ: “Regarding tor: AvoidDiskWrites 1 is a default. The tor log file has no sensitive data. Regarding general log files: There…” Mar 3, 22:39
John on FAQ: “What type of data is actively logged and stored on the torbox’s onboard storage? Does the torbox write all temporary…” Feb 10, 10:58
John Doe on Test VPN server and TorBox on a cloud capabilities and contribute with feedback: “Thanks for your feedback. I improved the blog post so that it would be easier to follow. For example, as…” Jan 24, 19:28