In this guide, we install TorBox 0.54 on a Raspberry Pi 3B model and walk through the first-boot configuration. The process is simple and requires only basic Linux knowledge. This guide is based on TorBox 0.54, which uses Debian 12 Bookworm as its base system.
TorBox turns your Raspberry Pi into a WiFi access point that routes all traffic through Tor. The setup is automated, but the first start asks for several important choices. This article explains each step and clarifies the options that many users find confusing.
The network diagram depicted in Figure 1 illustrates the TorBox Access Point setup using a Raspberry Pi 3B. The Pi's eth0 interface connects to the Mikrotik router (acting as the DHCP/DNS server) for Internet access (192.168.88.x/24 subnet). The wlan0 interface broadcasts the TorBox054 SSID (192.168.42.x/24 subnet), serving as a Wi-Fi Access Point for the TorBox-client. All client traffic is routed through Tor.
Figure 1 - TorBox Installed on Raspberry PI 3B a connected to Mikrotik Router
1. Downloading and Flashing TorBox
Download the TorBox image:
$ wget https://www.torbox.ch/data/torbox-20250720-v054.img.xz
Decompress and write the image to an SD card or USB stick (dve/sdb):
$ xz -d torbox-20250720-v054.img.xz -c | sudo dd of=/dev/sdb bs=4M status=progress && sync
Replace /dev/sdb with your correct storage device.
2. First Boot Initialization
Insert the freshly flashed card and boot the Raspberry Pi. TorBox starts a first-boot initialization. During this stage, TorBox:
- sets new default passwords
- generates configuration files
- configures the Tor daemon
- sets firewall rules (iptables)
- enables NAT
- configures wlan0 as an Access Point
- starts the optional web interface
Log in on HDMI with username torbox and password CHANGE-IT. The welcome window appears (Figure 2).
Figure 2 - First Start Up - Initial Window
The first dialog allows you to change the default hostname TorBox054. This is optional.
The next screen asks about countermeasures against tightly configured firewalls (Figure 3) so only ports 80 a 443 will be used. Select No.
Figure 3 - First Start Up - Tor Ports Configuration
Select Option 1 on the Internet configuration screen (Figure 4). We are assigning the onboard Ethernet interface (eth0) to the Internet connection, and the built-in wireless interface (wlan0) to function as the Access Point (AP) for client devices.
Figure 4 - First Start Up - Eth0 for Internet Connection and wlan0 for AP
Proceed to the next screen and select the 'Open Access' option for connecting to the Internet. (Figure 5).
Figure 5 - First Start Up - Open Access Connectivity to the Internet
On the next screen, activate TorBox's Automatic Counter Action (TACA). It provides a better Tor experience, especially on connections with lower bandwidth.
Next, set the correct time. Accurate time is important for Tor. Wrong clock values may cause Tor bootstrap failures.
Select 'No' to skip activating bridges (Figure 6). Bridges utilize pluggable transports to hide the Tor connection, but this option is not recommended. It is slower and generally ineffective behind a tightly configured firewall.
Figure 6 - First Start Up - Bridges Configuration
Finally, the initial setup ends with Bootstrapped 100% (Figure 7). At this moment, Tor is fully operational.
Figure 7 - First Start Up - Tor is Operational
Press Q and then ESC to exit the menu.
3. Connecting to TorBox
By default, TorBox broadcasts SSID Torbox054:
- SSID: TorBox054
- Password: CHANGE-IT
The client receives an IP address from the subnet:
- Client IP: 192.168.42.11/24
- TorBox (gateway): 192.168.42.1
We can manage TorBox by:
- SSH: ssh torbox@192.168.42.1
- Password: CHANGE-IT
Alternatively, we can use HTTP Web Interface at: http://192.168.42.1:
Figure 8 - TorBox Management using HTTP
- Username: torbox
- Password: CHANGE-IT
4. Notes About Raspberry Pi 3B
TorBox can run on a Raspberry Pi 3B, but it is not recommended for long-term use. Users report:
- latency spikes
- freezes after long uptime
- WiFi driver issues
- occasional loss of Internet connectivity
The Pi 3B may work for testing, but not for stable operation. The TorBox team recommends newer hardware (Pi 4).
My Raspberry Pi 3B unit also freezes the onboard WiFi interface. A simple workaround is to keep the interface active by sending periodic pings to a non-existing IP in the local subnet. This prevents the brcmfmac driver from entering a problematic power-save state.
4.1 Create the keepalive script
The script continuously sends a ping to a non-existent IP address on your local subnet. For instance, if your Wifi network is 192.168.42.0/24, use the IP 192.168.1.128.
Do not use a TorBox IP address (e.g. 192.168.42.1) assigned to wlan0.
The script should runs indefinitely, sending a single ping request every 2 seconds. It extracts the subnet of wlan0 and pings the address ending in .128. This IP address is not reachable. However, you can use a valid IP address assigned to the host from from DHCP server running on TorBox. The goal only is to wake the WiFi driver.
$ sudo su
# vi /usr/local/wlan-unfreeze.sh
#!/bin/bash
IFACE="wlan0"
LAST_OCTET="128"
while true; do
ping -I "$IFACE" -c1 -W1 $(ip -4 addr show "$IFACE" | grep -oP '(?<=inet\s)\d+\.\d+\.\d+\.')$LAST_OCTET >/dev/null 2>&1
sleep 2
done
Make it executable:
# chmod +x /usr/local/wlan-unfreeze.sh
4.2 Create the systemd service
# vi /etc/systemd/system/wlan-unfreeze.service
[Unit]
Description=TorBox WiFi Keepalive Ping
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/wlan-unfreeze.sh
Restart=always
RestartSec=5
User=root
StandardOutput=null
StandardError=journal
[Install]
WantedBy=multi-user.target
4.3 Activate service
Reload systemd configuration so it recognizes the newly created wlan-unfreeze.service file.
# sudo systemctl daemon-reload
Enable the service to start automatically every time the system boots up.
# systemctl enable wlan-unfreeze.service
Starts the service immediately for the current session, without requiring a reboot.
# systemctl start wlan-unfreeze.service
5. Testing
Connect to the Wi-Fi network provided by TorBox and visit https://check.torproject.org/. You should see a confirmation screen similar to the one shown in Figure 9.
Figure 9 - Wireless clients connected TorBox are Using Tor Network for HTTP Connection
Conclusion
TorBox offers a simple and way to route all network traffic through the Tor network. The first-boot wizard makes the initial setup easy, and this guide explains each choice so new users can avoid common mistakes. Once installed, TorBox provides a fully functional Tor WiFi access point.
If you install TorBox on a Raspberry Pi 3B, be aware that this hardware often suffers from WiFi freezes. For stable operation, the keepalive ping hack is required. Without it, wlan0 may stop responding, causing loss of connectivity and inaccessible SSH sessions. Newer Raspberry Pi models do not have this issue and are recommended for long-term use.
With the workaround applied and TorBox configured, you can browse anonymously on any device connected to the TorBox access point.