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:
- Using our image file (this is the recommended default way)
- Using our installation script
- Installation from scratch
- Addendum: How to connect to a wireless network from the CLI?
There are additional installation scripts for other systems, which may also run on different hardware platforms. However, TorBox’s implementation on other systems and hardware is experimental because we lack the resources to verify all the details across various installations. You can help us with reporting errors back to us.
• • •
Using our image file on a Raspberry Pi (recommended!)
This is the recommended and probably most straightforward way to install TorBox on a Raspberry Pi:
- Download the latest TorBox image (TorBox v.0.5.4 based on Raspberry Pi OS “Bookworm” lite 64bit with the Linux Kernel 6.6.62 and Tor version 0.4.8.16 with obfs4proxy version 0.0.14 and Snowflake 2.11.0; ~1 GB) and verify the integrity of the downloaded file.
- Transfer the downloaded image file to a SD Card. Due to the significantly improved compression rate, we compress the images using xz. By default, Balena Etcher and Raspberry Pi Imager support this kind of compressed image, but sometimes one or the other fails with an error message to flash it correctly on a SD Card. In this case, you need to decompress the .xz file first. TorBox needs at least an 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 flickering, connect your client to the new WiFi “TorBox054” (password: CHANGE-IT).
- Login to the TorBox by using a SSH client (192.168.42.1 on a WiFi client, 192.168.43.1 on a cable client or 192.168.44.1 when connected via VPN or if you use TorBox mini on a Raspberry Pi Zero 2 W as a RNDIS/Ethernet Gadget) or a web browser (http://192.168.42.1 on a WiFi client, http://192.168.43.1 on a cable client or 192.168.44.1 when connected via VPN; 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. Immediately, you should change the default passwords (the associated entries are placed in the configuration sub-menu).
We recommend running TorBox on a Raspberry Pi 3 Model B+, a Raspberry Pi 4 Model B or a Raspberry Pi 5. We also offer installation scripts for other systems, which might run on older (32-bit) or other hardware platforms.
• • •
Using our installation script on a Raspberry Pi with Raspberry Pi OS Lite
This is likely the most efficient method for installing TorBox. With that method, you will have the latest version of the base system and the TorBox menu and won’t have to wait for the next release of the image file.
- Download the latest version of Raspberry Pi OS Lite (64-bit) or Raspberry Pi OS Lite (32-bit), or use the Raspberry Pi Imager and choose, under
Operating System
,Raspberry Pi OS (other)
,Raspberry Pi OS Lite (64-bit)
orRaspberry Pi OS Lite (32-bit)
image. - If you don’t use the Raspberry Pi Imager, then transfer the downloaded Raspberry Pi OS Lite image to an SD Card, for example, with Etcher. TorBox needs at least an 8 GB SD Card.
- If asked, create a user “torbox” and remember the chosen password for later use.
- Optionally, localise your installation.
- 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 fork_owner_name] [--select-branch branch_name] [--on_a_cloud] [--torbox_mini] [--continue_with_step n] [--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)
--on_a_cloud : Installing on a cloud or as a cloud service
--torbox_mini : Installing TorBox mini on a Raspberry Pi Zero 2 W
--step_by_step : Executes the installation step by step
--continue_with_step n
: Continue the installation with a certain step
- Restart the system; after 2-3 minutes, when the green LED stops flickering, connect your client to the new WiFi “TorBox054” (password: CHANGE-IT).
- Login to the TorBox by using a SSH client (192.168.42.1 on a WiFi client, 192.168.43.1 on a cable client or 192.168.44.1 when connected via VPN or if you use TorBox mini on a Raspberry Pi Zero 2 W as a RNDIS/Ethernet Gadget) or a web browser (http://192.168.42.1 on a WiFi client, http://192.168.43.1 on a cable client or 192.168.44.1 when connected via VPN; 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. Immediately, you should change the default passwords (the associated entries are placed in the configuration sub-menu.
• • •
Using scripts for other systems and hardware platforms
We tested the installation only on a Raspberry Pi 4 and a Raspberry Pi 5, but it should also work on an older Raspberry Pi if the correct image is used:
Operating System | OS image | Script | Remarks & Restrictions |
Debian 12 (Bookworm) Important: Currently, Debian Images are not working with the Raspberry Pi 5 | Raspberry Pi Debian Images | run_install_on_debian.sh (installation script for Debian-based systems) | ➔ see Footnotes 1 |
DietPi based on Debian 12 (Bookworm) Important: Currently, DietPi support is in a test phase | DietPi image download | run_install_on_debian.sh (installation script for Debian-based systems) | ➔ see Footnotes 2 |
Ubuntu Server 24.04 LTS | Ubuntu on a Raspberry Pi or use the Raspberry Pi Imager | run_install_on_ubuntu.sh (installation script for Ubuntu-based systems) | ➔ see Footnotes 3 |
To install TorBox on another system or hardware, download the OS image and transfer it to an SD Card. Under Debian and DietPi, log into your server as root
. With Ubuntu, log into your server as a user (for example, ubuntu
or 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_debian.sh [-h|--help] [--randomize_hostname] [--select-tor] [--select-fork fork_owner_name] [--select-branch branch_name] [--on_a_cloud] [--torbox_mini] [--continue_with_step n] [--step_by_step]
run_install_on_ubuntu.sh [-h|--help] [--randomize_hostname] [--select-tor] [--select-fork fork_owner_name] [--select-branch branch_name] [--on_a_cloud] [--continue_with_step n] [--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)
--on_a_cloud : Installing on a cloud or as a cloud service
--torbox_mini : Installing TorBox mini on a Raspberry Pi Zero 2 W (only with run_install_on_debian.sh)
--step_by_step : Executes the installation step by step
--continue_with_step n
: Continue the installation with a certain step
- Restart the system; after 2-3 minutes, when the green LED stops flickering, connect your client to the new WiFi “TorBox054” (password: CHANGE-IT).
- Login to the TorBox by using a SSH client (192.168.42.1 on a WiFi client, 192.168.43.1 on a cable client or 192.168.44.1 when connected via VPN or if you use TorBox mini on a Raspberry Pi Zero 2 W as a RNDIS/Ethernet Gadget) or a web browser (http://192.168.42.1 on a WiFi client, http://192.168.43.1 on a cable client or 192.168.44.1 when connected via VPN; 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. Immediately, you should change the default passwords (the associated entries are placed in the configuration sub-menu.
Footnotes to Remarks & Restrictions
Footnotes 1 regarding Debian 12 (Bookworm):
- Log into the freshly prepared Debian system using
root
. - Before you can use
wget
, you have to prepare the Debian system:
.- Ensure you are connected to the Internet (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
- Important: Not all required Python modules can be installed in one run. If you were asked if you would like to try it again, answer with Y.
- After installing TorBox and starting up the fresh Debian 12 (Bookworm) system, you might wait one or two minutes until you can log in.
- Debian on a Raspberry Pi may have more problems with wireless adapters and their drivers than the Raspberry Pi OS.
Footnotes 2 regarding DietPi based on Debian 12 (Bookworm):
- Log into the freshly prepared DietPi system using
root
and as a passworddietpi
. - At the end of the DietPi configuration tool called “DietPi-Software”, which runs on a freshly installed DietPi system, change the SSH server from
Dropbear
toOpenSSH Server
and useInstall Software
. - Important: Not all required Python modules can be installed in one run. If you were asked if you would like to try it again, answer with Y.
- A TorBox on a DietPi system requires only about two-thirds of the space compared to a TorBox on a Raspberry Pi system.
Footnotes 3 regarding Ubuntu Server 22.04.2 LTS and Ubuntu Server 23.04:
- Log into the freshly prepared Ubuntu system as a user (for example,
ubuntu
ortorbox
). - 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”.
- Ubuntu’s support for network drivers appears to be better than that of 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. - Especially at the beginning, after a freshly installed TorBox, sometimes, the user is asked to type in his password.
- Sometimes, Ubuntu has compatibility issues with SSH terminals.
• • •
Installation from scratch on a Raspberry Pi with Raspberry Pi OS Lite
This is probably the safest, but also the most complex and time-consuming method for installing 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.
For more information, go to our detailed manual.
• • •
Addendum: How to Connect to a Wireless Network from the Command-Line Interface (CLI)?
The easiest and most reliable way to install TorBox using one of the installation scripts is to connect the Raspberry Pi to an Ethernet network. Using the onboard wireless chip is a bit more complicated, mainly because we don’t want to install and start a Graphical User Interface. Since not everyone has the correct procedure in mind for connecting a wireless network via the CLI, we will guide you through it.
- We assume that you logged in as
root
. If this is not the case, you may usesudo
in front of the commands. - Unblock the wireless interfaces with
rfkill unblock wlan
. - Stop an already running
wpa_supplicant
withsystemctl 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