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:

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) or Raspberry 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 password dietpi.
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 to OpenSSH Server and use Install 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 or torbox).
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 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 TorBox v.0.5.4 – Security Update 17 April 2025: “Check out the top of the post. There you will find two images: TorBox Image and TorBox mini Image. You…” May 9, 20:35
ke on TorBox v.0.5.4 – Security Update 17 April 2025: “what configuration you want to use The hardware setup would be: Raspberry pi zero 2 w, micro usb power supply…” May 9, 12:21
John Doe on TorBox v.0.5.4 – Security Update 17 April 2025: “Going to the Beagle Bone Distro page, I can find a Debian 11 image for BeagleBone Black. I also found…” May 4, 10:33
John Doe on TorBox v.0.5.4 – Security Update 17 April 2025: “The TorBox mini is configured that way: Internet is on wlan0 Client is on eth0 (RNDIS/Ethernet Gadget mode). These are…” May 4, 10:08
ke on TorBox v.0.5.4 – Security Update 17 April 2025: “torbox mini 0.5.4 from apr 2025 does not work. It does work. I made a mistake with the ssh command.” May 1, 13:52