Whether you like to implement TorBox in an existing system, on another hardware, or on another operating system, or you don’t trust an image file which you didn’t bundle yourself, this detailed manual helps you build a TorBox from scratch.

This manual is written for Raspberry Pi OS “Bookworm” Lite (64-bit) (based on Debian 13 “Trixie”) on a Raspberry Pi 3 Model B+, a Raspberry Pi 4 Model B or a Raspberry Pi 5. However, this manual should also work with the 32-bit version of Raspberry Pi OS and older Raspberry Pi models.

Before you create all configuration files by yourself, some of the below-mentioned configuration files are stored in the “etc” folder in our GitHub repository.

Table Of Contents

1. Prepare your system
2. Update your system and install all necessary packages
3. Compiling, installing and configuring Tor
4. Installing the TorBox Menu (and downloading all configuration files)
5. Setting up a DHCP server
6. Setting up network interfaces
7. Configuring the TorBox AP
8. Configuring Network Address Translation (NAT)
9. Configuring Nginx to work with WebSSH and Onion Services
10. Disable Bluetooth
11. Update sudo setup
12. Stop logging, preparing for the first start and restarting the system

• • •

1. Prepare your system

Download the latest version of Raspberry Pi OS “Trixie” Lite (64-bit), or use the Raspberry Pi Imager and, under Operating System, choose Raspberry Pi OS (other) and the Raspberry Pi OS Lite (64-bit) image.
If you didn’t use the Raspberry Pi Imager, then transfer the downloaded Raspberry Pi OS Lite image to an SD Card, for example, with Balena Etcher. TorBox needs at least an 8 GB SD Card.
If asked, create a user torbox and remember the chosen password for later use.
Log in to your newly set up system as torbox and with your chosen password.
Log in to your newly set up system and configure it with sudo raspi-config.
Important
– You must set the WLAN country (in raspi-config menu entry 5 – L4), or TorBox doesn’t work because WiFi is blocked!!
– Also, disable the auto-login feature (in raspi-config menu entry 1 – S5 – B1)
– You need to have a stable internet connection.

An alternative way to unblock WiFi on Raspberry Pi OS without using raspi-config:

sudo iw reg set US
sudo sed -i "s/^REGDOMAIN=.*/REGDOMAIN=US/" /etc/default/crda
sudo rfkill unblock wlan

An alternative way to disable the auto-login feature:

sudo raspi-config nonint do_boot_behaviour B1

To overcome cheap censorship during the installation, put some well-known public name servers into /etc/resolv.conf:

sudo printf "nameserver 1.1.1.1nnameserver 1.0.0.1nnameserver 8.8.8.8nnameserver 8.8.4.4n" | sudo tee /etc/resolv.conf

• • •

2. Update your system and install all necessary packages

Some packages have to be installed to build a TorBox from scratch. To be sure to have the latest version of the base system, the package list, and the firmware, you should use the following commands:

sudo apt-get -y update
sudo apt-get -y dist-upgrade
sudo apt-get -y clean
sudo apt-get -y autoclean
sudo apt-get -y autoremove

Depending on the updated packages (firmware, kernel, driver etc.) a reboot is recommended.

The following additional packages are necessary and have to be installed:

hostapd -> provides a wireless access point (AP).
isc-dhcp-client, isc-dhcp-server -> DHCP client and server – we need both of them.
iptables, ipset -> administration tools for packet filtering and NAT.
tor-geoipd, apt-transport-tor -> gives access to the Tor network (tor will be installed later, see further below).
nyx -> a command-line monitor for Tor.
usbmuxd -> a socket daemon to multiplex connections from and to iOS devices (support for tethering with iOS devices).
dnsmasq -> DNS forwarder (necessary to deal with captive portals).
dnsutils, tcpdump, iftop, vnstat -> analytical and statistical network tools.
debian-goodies, apt-transport-https, ca-certificates, bind9-dnsutils -> other necessary tools.
dirmngr -> GNU privacy guard – network certificate management service.
imagemagick, tesseract-ocr, libjpeg-dev -> necessary libraries and programs for some Python scripts.
qrencode, nginx, basez -> necessary for Onion Services implementation.
ntpsec-ntpdate -> necessary to set the correct system time.
macchanger -> utility for manipulating the MAC address of network interfaces. Important: macchanger will ask for enabling an automatic change of the MAC address – REPLY WITH NO!
screen -> a terminal multiplexer allowing users to access multiple login sessions inside a single terminal window, or detach and reattach sessions from a terminal.
git -> distributed revision control system.
openvpn, openssl -> software that implements virtual private network.
ppp -> Point-to-Point Protocol
linux-headers-$(uname -r), dkms -> necessary to compile / install additional drivers
lshw -> Detailed information about the peripheral devices
ifupdown -> ifup and ifdown, used to configure network interfaces
build-essential, automaker, libevent-dev, libssl-dev, asciidoc, bc, devscripts, dh-apparmor, libcap-dev, liblzma-dev, libsystemd-dev, libzstd-dev, quilt, zlib1g-dev -> installation of developer packages for the compilation of tor

Install all necessary packages with the following command:

# Installation of standard packages
sudo apt-get -y install hostapd isc-dhcp-client isc-dhcp-server usbmuxd 
dnsmasq bind9-dnsutils tcpdump iftop vnstat debian-goodies 
apt-transport-https dirmngr imagemagick tesseract-ocr ntpsec-ntpdate 
screen git openvpn ppp nyx apt-transport-tor qrencode nginx basez iptables 
ipset macchanger openssl ca-certificates lshw linux-headers-$(uname -r) dkms 
libjpeg-dev ifupdown

# If you use a Debian distribution instead of Raspberry Pi OS, you may need to 
# install the following additional packages
apt-get -y install wget curl gnupg net-tools unzip sudo rfkill resolvconf

# If you use a Ubuntu distribution instead of Raspberry Pi OS, you may need to 
# install the following additional packages
sudo apt-get -y install net-tools unzip equivs rfkill iw

# Installation of developper packages - THIS PACKAGES ARE NECESARY FOR THE 
# COMPILATION OF TOR!! Without them, tor will disconnect and restart every 
# 5 minutes!!
sudo apt-get -y install build-essential automake libevent-dev libssl-dev 
asciidoc bc devscripts dh-apparmor libcap-dev liblzma-dev libsystemd-dev 
libzstd-dev quilt zlib1g-dev

# IMPORTANT tor-geoipdb installs also the tor package. In an authoritarian 
# country, you may mask tor and activate it later with OBFS4 bridge support 
# to hide the use of tor.
sudo systemctl mask tor
sudo apt-get -y install tor-geoipdb
sudo systemctl mask tor
sudo systemctl stop tor

# Installation of needed Python modules
# Enable the possibility to manage Python modules with pip3
sudo rm "/usr/lib/python3.12/EXTERNALLY-MANAGED"
# or
sudo rm "/usr/lib/python3.13/EXTERNALLY-MANAGED"

# Installation of some basic Python packages
sudo apt-get -y install python3-pip
sudo pip install --ignore-installed --upgrade pip
sudo pip3 install --ignore-installed pipenv

# Generate and install the requirements
wget --no-cache https://raw.githubusercontent.com/radio24/TorBox/master/Pipfile.lock
pipenv requirements >requirements.txt
sudo sed -i "/^pip==.*/d" requirements.txt
sudo sed -i "s/^typing-extensions==/typing_extensions==/g" requirements.txt
# IMPORTANT: All requierements have to be installed, which is not always the case after executing the command below for the first time.
# In this case, you have to execute the command multiple times until all requirements are installed.
sudo pip3 install --ignore-installed -r requirements.txt

# Installation of go 
#
# ATTENTION
# For a Raspberry Pi OS 32bit, you must use go1.25.5.linux-armv6l.tar.gz 
# (with a l like LIMA and not with a one (1)). Also, see here for all the 
# different packages depending on the hardware and the operating system:
# https://go.dev/dl/
cd
sudo rm -rf /usr/local/go
wget https://golang.org/dl/go1.25.5.linux-arm64.tar.gz
sudo tar -C /usr/local -xzvf go1.25.5.linux-arm64.tar.gz
export PATH=$PATH:/usr/local/go/bin
sudo printf "n# Added by TorBoxnexport PATH=$PATH:/usr/local/go/binn" | sudo tee -a .profile

# Create a folder "openvpn" for *.ovpn files
sudo mkdir /home/torbox/openvpn
sudo chown -R torbox:torbox /home/torbox/

We don’t want to start dnsmasq automatically after booting the system:

sudo systemctl disable dnsmasq
sudo systemctl daemon-reload

• • •

3. Compiling, installing and configuring Tor

There are at least three ways to install Tor:

From the Raspberry Pi OS itself: this has probably already happened with the installation of tor-geoipdb. This method is recommended in authoritarian countries. However, usually, it installs an older, long-term-supported version of tor.
From the Debian repository of the TorProject: we don’t recommend using this method because it doesn’t support 32-bit ARM systems/OS.
From the official Tor repositories on GitHub: we recommend this method as the standard way to install tor on the TorBox (used below).

First step: Compiling and installing a specific version of tor from the official Tor repositories on GitHub
Select a specific tor version from the unofficial Tor repositories on GitHub (alpha versions are not recommended!). Copy the link of the source code file (the tar.gz file). You need that link for the wget command below.

wget https://gitlab.torproject.org/tpo/core/tor/-/archive/tor-<version>/tor-tor-<version>.tar.gz
tar xzf tor-tor-<version>.tar.gz
cd <torversion>
git init
git add -- *
git config --global user.name "torbox"
git config --global user.email "torbox@localhost"
git commit -m "Initial commit"
sh autogen.sh
sh configure --disable-unittests
make
sudo make install
cd
sudo rm -r tor-*
sudo mv /usr/local/bin/tor* /usr/bin

Second step: Installation of obfs4proxy and Snowflake

# Installation of obfs4proxy
cd
git clone https://salsa.debian.org/pkg-privacy-team/obfs4proxy.git
export GO111MODULE="on"
cd obfs4proxy
go build -o obfs4proxy/obfs4proxy ./obfs4proxy
sudo cp ./obfs4proxy/obfs4proxy /usr/bin
cd
sudo rm -rf obfs4proxy
sudo rm -rf go*

# Installation of Snowflake
cd
git clone https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowflake
export GO111MODULE="on"
cd snowflake/proxy
go get
go build
sudo cp proxy /usr/bin/snowflake-proxy
cd
cd snowflake/client
go get
go build
sudo cp client /usr/bin/snowflake-client
cd
sudo rm -rf snowflake
sudo rm -rf go*

Third step: Configuring Tor

## This is the configuration file of Tor

## DON'T CHANGE THE FOLLOWING LINES!
######################################################
## Configuration for TorBox

#BandwidthRate 1 GB
#BandwidthBurst 1 GB
Log notice file /var/log/tor/notices.log
# IPv6 support (only)
#ClientUseIPv6 1
VirtualAddrNetworkIPv4 10.192.0.0/10
AutomapHostsSuffixes .onion,.exit
AutomapHostsOnResolve 1
TransPort 127.0.0.1:9040
#TransPort 192.168.42.1:9040
#TransPort 192.168.43.1:9040
#TransPort 192.168.44.1:9040
DNSPort 127.0.0.1:9053
#DNSPort 192.168.42.1:9053
#DNSPort 192.168.43.1:9053
#DNSPort 192.168.44.1:9053
SocksPort 127.0.0.1:9050
#SocksPort 192.168.42.1:9050
#SocksPort 192.168.43.1:9050
#SocksPort 192.168.44.1:9050
SocksPort 127.0.0.1:9052 IsolateDestAddr
#SocksPort 192.168.42.1:9052 IsolateDestAddr
#SocksPort 192.168.43.1:9052 IsolateDestAddr
#SocksPort 192.168.44.1:9052 IsolateDestAddr
ControlPort 127.0.0.1:9051
#ControlPort 192.168.42.1:9051
#ControlPort 192.168.43.1:9051
#ControlPort 192.168.44.1:9051
HashedControlPassword 16:E68F16640ED8C0F7601F5AA3D229D8DFD8715623CB055577F9434F7FB7
DisableDebuggerAttachment 0
AvoidDiskWrites 1
#%include /etc/tor/torrc.exclude-slow

## THE CONFIGURATION OF THE ONION SERVICES STARTS HERE!
#######################################################
## This will configure the Onion Services (do not remove or change that line - this is an anchor)

## This will configure the Onion Service authorizations
#ClientOnionAuthDir /var/lib/tor/onion_auth

## THE CONFIGURATION OF THE BRIDGE RELAY STARTS HERE!
######################################################
## This will setup an obfs4 bridge relay.
#BridgeRelay 1
#ORPort 4235
#ExtORPort auto
#ServerTransportPlugin obfs4 exec /usr/bin/obfs4proxy
#ServerTransportListenAddr obfs4 0.0.0.0:443
#ContactInfo <[email protected]>
#Nickname TorBox055
#BridgeDistribution any

## TO OVERCOME A FIREWALL, START HERE!
## HOWEVER, USE IT ONLY, IF REALLY NECESSARY!
######################################################
## This will allow you to run Tor as a client behind a firewall with
## restrictive policies, but will not allow you to run as a server behind such
## a firewall.
## ReachableAddresses IP[/MASK][:PORT]…
## A comma-separated list of IP addresses and ports that your firewall allows
## you to connect to. The format is as for the addresses in ExitPolicy, except
## that "accept" is understood unless "reject" is explicitly provided. For
## example, 'ReachableAddresses 99.0.0.0/8, reject 18.0.0.0/8:80, accept *:80'
## means that your firewall allows connections to everything inside net 99,
## rejects port 80 connections to net 18, and accepts connections to port 80
## otherwise.
#ReachableAddresses accept *:443, accept *:80

## TO OVERCOME CENSORSHIP, START HERE!
######################################################
## If you like to use bridges to overcome censorship, EDIT THE LINES BELOW!
## To use bridges, uncomment the three lines below...
#UseBridges 1
#UpdateBridgesFromAuthority 0
#ClientTransportPlugin meek_lite,obfs4 exec /usr/bin/obfs4proxy
#ClientTransportPlugin snowflake exec /usr/bin/snowflake-client

## Meek-Azure (do not remove or change that line - this is an anchor)
#Bridge meek_lite 192.0.2.20:80 url=https://1603026938.rsc.cdn77.org front=www.phpmyadmin.net utls=HelloRandomizedALPN

## Snowflake (do not remove or change that line - this is an anchor)
#Bridge snowflake 192.0.2.3:80 2B280B23E1107BB62ABFC40DDCC8824814F80A72 fingerprint=2B280B23E1107BB62ABFC40DDCC8824814F80A72 url=https://snowflake-broker.torproject.net/ ampcache=https://cdn.ampproject.org/ front=www.google.com ice=stun:stun.l.google.com:19302,stun:stun.antisip.com:3478,stun:stun.bluesip.net:3478,stun:stun.dus.net:3478,stun:stun.epygi.com:3478,stun:stun.sonetel.com:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.voys.nl:3478 utls-imitate=hellorandomizedalpn
#Bridge snowflake 192.0.2.3:80 2B280B23E1107BB62ABFC40DDCC8824814F80A72 fingerprint=2B280B23E1107BB62ABFC40DDCC8824814F80A72 url=https://1098762253.rsc.cdn77.org/ fronts=www.cdn77.com,www.phpmyadmin.net ice=stun:stun.l.google.com:19302,stun:stun.antisip.com:3478,stun:stun.bluesip.net:3478,stun:stun.dus.net:3478,stun:stun.epygi.com:3478,stun:stun.sonetel.com:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.voys.nl:3478 utls-imitate=hellorandomizedalpn
#Bridge snowflake 192.0.2.4:80 8838024498816A039FCBBAB14E6F40A0843051FA fingerprint=8838024498816A039FCBBAB14E6F40A0843051FA url=https://1098762253.rsc.cdn77.org/ fronts=www.cdn77.com,www.phpmyadmin.net ice=stun:stun.l.google.com:19302,stun:stun.antisip.com:3478,stun:stun.bluesip.net:3478,stun:stun.dus.net:3478,stun:stun.epygi.com:3478,stun:stun.sonetel.net:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.voys.nl:3478 utls-imitate=hellorandomizedalpn
#Bridge snowflake 192.0.2.3:80 2B280B23E1107BB62ABFC40DDCC8824814F80A72 fingerprint=2B280B23E1107BB62ABFC40DDCC8824814F80A72 url=https://1098762253.rsc.cdn77.org/ fronts=app.datapacket.com,www.datapacket.com ice=stun:stun.epygi.com:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.mixvoip.com:3478,stun:stun.nextcloud.com:3478,stun:stun.bethesda.net:3478,stun:stun.nextcloud.com:443 utls-imitate=hellorandomizedalpn
#Bridge snowflake 192.0.2.4:80 8838024498816A039FCBBAB14E6F40A0843051FA fingerprint=8838024498816A039FCBBAB14E6F40A0843051FA url=https://1098762253.rsc.cdn77.org/ fronts=app.datapacket.com,www.datapacket.com ice=stun:stun.epygi.com:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.mixvoip.com:3478,stun:stun.nextcloud.com:3478,stun:stun.bethesda.net:3478,stun:stun.nextcloud.com:443 utls-imitate=hellorandomizedalpn
#Specific Snowflake bridge for China
#Bridge snowflake 192.0.2.3:80 2B280B23E1107BB62ABFC40DDCC8824814F80A72 fingerprint=2B280B23E1107BB62ABFC40DDCC8824814F80A72 url=https://snowflake-broker.torproject.net.global.prod.fastly.net/ front=foursquare.com ice=stun:stun.l.google.com:19302,stun:stun.antisip.com:3478,stun:stun.bluesip.net:3478,stun:stun.dus.net:3478,stun:stun.epygi.com:3478,stun:stun.sonetel.com:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.voys.nl:3478 utls-imitate=hellorandomizedalpn
#Specific Snowflake bridge for China
#Bridge snowflake 192.0.2.4:80 8838024498816A039FCBBAB14E6F40A0843051FA fingerprint=8838024498816A039FCBBAB14E6F40A0843051FA url=https://snowflake-broker.torproject.net.global.prod.fastly.net/ front=foursquare.com ice=stun:stun.l.google.com:19302,stun:stun.antisip.com:3478,stun:stun.bluesip.net:3478,stun:stun.dus.net:3478,stun:stun.epygi.com:3478,stun:stun.sonetel.net:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.voys.nl:3478 utls-imitate=hellorandomizedalpn
#Specific Snowflake bridge for Iran
#Bridge snowflake 192.0.2.3:80 2B280B23E1107BB62ABFC40DDCC8824814F80A72 fingerprint=2B280B23E1107BB62ABFC40DDCC8824814F80A72 url=https://snowflake-broker.azureedge.net/ front=ajax.aspnetcdn.com ice=stun:stun.voip.blackberry.com:3478,stun:stun.altar.com.pl:3478,stun:stun.antisip.com:3478,stun:stun.bluesip.net:3478,stun:stun.dus.net:3478,stun:stun.epygi.com:3478,stun:stun.sonetel.com:3478,stun:stun.sonetel.net:3478,stun:stun.stunprotocol.org:3478,stun:stun.uls.co.za:3478,stun:stun.voipgate.com:3478,stun:stun.voys.nl:3478 utls-imitate=hellorandomizedalpn
#Specific Snowflake bridge for Turkmenistan
#Bridge snowflake 192.0.2.3:80 2B280B23E1107BB62ABFC40DDCC8824814F80A72 fingerprint=2B280B23E1107BB62ABFC40DDCC8824814F80A72 url=https://snowflake-broker.torproject.net.global.prod.fastly.net/ front=foursquare.com ice=stun:206.53.159.130:3479,stun:94.23.17.185:3479,stun:217.74.179.29:3479,stun:83.125.8.47:3479,stun:23.253.102.137:3479,stun:52.26.251.34:3479,stun:154.73.34.8:3479,stun:185.125.180.70:3479,stun:195.35.115.37:3479 utls-imitate=hellorandomizedalpn
#Specific Snowflake bridge for Turkmenistan
#Bridge snowflake 192.0.2.4:80 8838024498816A039FCBBAB14E6F40A0843051FA fingerprint=8838024498816A039FCBBAB14E6F40A0843051FA url=https://snowflake-broker.torproject.net.global.prod.fastly.net/ front=foursquare.com ice=stun:206.53.159.130:3479,stun:94.23.17.185:3479,stun:217.74.179.29:3479,stun:83.125.8.47:3479,stun:23.253.102.137:3479,stun:52.26.251.34:3479,stun:154.73.34.8:3479,stun:185.125.180.70:3479,stun:195.35.115.37:3479 utls-imitate=hellorandomizedalpn

## IMPORTANT: Currently, Snowflake supports only one bridge line. If you uncomment several bridge lines, only the first will be used.

## OBFS4 bridges
##
## You have three ways to get new bridge-addresses:
## 1. Get them here https://bridges.torproject.org/
## 2. Or send an email to [email protected], using an address
##    from Riseup or Gmail with "get transport obfs4" in the body of the mail.
## 3. Via Telegram (official): https://t.me/GetBridgesBot ; then use /bridges to get a bridge.
## 4. (Not recommended, only if needed): Via Telegram (unofficial): https://t.me/tor_bridges

Important

Don’t remove or change the “#-lines”. TorBox changes this file automatically. If you delete values (even those with #), TorBox won’t re-add them, and It may not work correctly!
You can change the “HashedControlPassword” at the end of the installation using the configuration sub-menu entry 3.

Also, the Tor installation has to be prepared for onion services:

sudo mkdir /var/lib/tor/services
sudo chown -R debian-tor:debian-tor /var/lib/tor/services
sudo chmod -R go-rwx /var/lib/tor/services
sudo mkdir /var/lib/tor/onion_auth
sudo chown -R debian-tor:debian-tor /var/lib/tor/onion_auth
sudo chmod -R go-rwx /var/lib/tor/onion_auth

Fourth step: Configuring geoip and obfs4proxy

# Execute the following commands:
sudo chmod a+x /usr/share/tor/geoip*
sudo cp /usr/share/tor/geoip* /usr/bin
sudo setcap 'cap_net_bind_service=+ep' /usr/bin/obfs4proxy
sudo sed -i "s/^NoNewPrivileges=yes/NoNewPrivileges=no/g" /lib/systemd/system/[email protected]
sudo sed -i "s/^NoNewPrivileges=yes/NoNewPrivileges=no/g" /lib/systemd/system/[email protected]

• • •

4. Installing the TorBox Menu (and downloading all configuration files)

The “TorBox Menu” is a user-friendly way to change your TorBox settings. The menu is automatically started whenever a Terminal, 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 or using TorBox mini) access the TorBox. The menu uses shell scripts that configure the correct packet filtering and NAT rules and start other supporting tools. All scripts are located in ~/torbox and ~/torbox/bin; all configuration files are located in ~/torbox/etc. If necessary, the menu can be started there with ./menu. Use the following commands to install the menu (or download the complete TorBox repository from our GitHub page):

# Execute the following commands:
cd
wget https://github.com/radio24/TorBox/archive/refs/heads/master.zip
unzip master.zip
mv TorBox-master torbox
rm -r master.zip

# Edit .profile:
sudo nano .profile

# Add the following lines to the end of ".profile":
cd torbox
bash menu

Optionally, in ~/torbox/etc/motd you can find a logo, which you can copy into your /etc/motd.

# Execute following commands:
cp ~/torbox/etc/motd /etc/motd

Finally, you need to change /etc/rc.local to be sure that TorBox will work properly after a restart:

# Execute following commands:
sudo cp etc/rc.local /etc/

Make sure that the SSH-client can access the TorBox after the restart:

# Execute the following commands:
sudo systemctl unmask ssh
sudo systemctl enable ssh
sudo systemctl start ssh
sudo systemctl daemon-reload

• • •

5. Setting up a DHCP server

# Set up your hostname (for example "TorBox" instead of "raspberrypi":
sudo hostnamectl set-hostname "TorBox"
sudo systemctl restart systemd-hostnamed
sudo nano /etc/hosts

# Adjust the configuration file of the DHCP server:
sudo nano /etc/dhcp/dhcpd.conf

# Replace /etc/dhcp/dhcpd.conf with the following content:
default-lease-time 600;
max-lease-time 7200;
ddns-update-style none;
authoritative;

subnet 192.168.42.0 netmask 255.255.255.0 {
range 192.168.42.10 192.168.42.50;
option broadcast-address 192.168.42.255;
option routers 192.168.42.1;
option domain-name "local";
option domain-name-servers 192.168.42.1;
}

subnet 192.168.43.0 netmask 255.255.255.0 {
range 192.168.43.10 192.168.43.50;
option broadcast-address 192.168.43.255;
option routers 192.168.43.1;
option domain-name "local";
option domain-name-servers 192.168.43.1;
}

# Adjust the configuration file of the DHCP server (isc-dhcp-server):
sudo nano /etc/default/isc-dhcp-server

# Add all the available interfaces to the following line:
INTERFACEv4="wlan0 wlan1 eth0 eth1 usb0"

The classless static route option (RFC3442) gives us some headaches with certain AP under certain conditions (see also here). Therefore, we remove this option from the configuration:

# Remove in /etc/dhcp/dhclient.conf the classless static route option
sudo nano /etc/dhcp/dhclient.conf

# Old entries:
option rfc3442-classless-static-routes code 121 = array of unsigned integer 8;

request subnet-mask, broadcast-address, time-offset, routers, domain-name,
domain-name-servers, domain-search, host-name, dhcp6.name-servers,
dhcp6.domain-search, dhcp6.fqdn, dhcp6.sntp-servers, netbios-name-servers,
netbios-scope, interface-mtu, rfc3442-classless-static-routes, ntp-servers; 

# New entries:
#option rfc3442-classless-static-routes code 121 = array of unsigned integer 8;

request subnet-mask, broadcast-address, time-offset, routers, domain-name,
domain-name-servers, domain-search, host-name, dhcp6.name-servers,
dhcp6.domain-search, dhcp6.fqdn, dhcp6.sntp-servers, netbios-name-servers,
netbios-scope, interface-mtu, ntp-servers;

• • •

6. Setting up network interfaces

Currently, TorBox supports the following connections:

INTERNET     CLIENT                Remarks
--------------------------------------------------------------------------------------------
ETH0         WLAN0(+ETH1+TUN1)     Ethernet cable (eth0) or TorBox on a cloud (tun1)
ETH1         WLAN0(+ETH0)          USB ethernet adapter or Tethering (iOS)
WLAN1        WLAN0(+ETH0)          Wireless network (USB adapter; wlan1)
WLAN0        WLAN1(+ETH0+USB0)     Wireless network or TorBox mini (onboard chip; wlan0)
USB0	     WLAN0(+ETH0)          USB dongle or Tethering (Android) (usb0)
PPP0         WLAN0(+ETH0)          Cellular-internet
TUN0         WLAN0(+ETH0)          Over a VPN connection

In the beginning, only the standard /etc/network/interface — listed below — is necessary. Depending on your choice in the TorBox menu, this file is automatically altered by TorBox.

# Edit /etc/network/interfcae:
sudo nano /etc/network/interface

# Replace /etc/network/interface with the following content:

# source-directory /etc/network/interfaces.d

auto lo
auto eth0
auto wlan1
auto usb0

iface lo inet loopback
iface eth0 inet dhcp
iface wlan1 inet dhcp
iface usb0 inet dhcp
allow-hotplug wlan0 wlan1 eth0 eth1 usb0

iface wlan0 inet static
  address 192.168.42.1
  netmask 255.255.255.0
	wireless-power off

iface eth1 inet static
  address 192.168.43.1
  netmask 255.255.255.0

• • •

7. Configuring the TorBox AP

# Edit /etc/hostapd/hostapd.conf
sudo nano /etc/hostapd/hostapd.conf

# Replace /etc/hostapd/hostapd.conf with the following content:
interface=wlan0
driver=nl80211
ssid=TorBox055
country_code=US
hw_mode=g
channel=6
ieee80211n=1
ieee80211ac=1
wmm_enabled=1
#ht_capab=[HT40-][HT40+][SHORT-GI-20][SHORT-GI-40][DSSS_CCK-40]
#vht_oper_chwidth=1
#vht_oper_centr_freq_seg0_idx=42
macaddr_acl=0
auth_algs=1
ignore_broadcast_ssid=0
wpa=2
wpa_passphrase=CHANGE-IT
wpa_key_mgmt=WPA-PSK
rsn_pairwise=CCMP

Important

Only letters (upper and lower case) and numbers are allowed in the passphrase. The length must be between 8 and 63 characters.
Don’t remove or change the “#-lines” and the country_code=US value! Otherwise, the 2.4 GHz 40 MHz and the 5 GHz 40 and 80 MHz settings will probably not work and will crash hostapd! In use, TorBox changes this file along with the selection in the configuration sub-menu. However, if you delete values (even those with #), TorBox doesn’t re-add them!

# Edit /etc/default/hostapd
sudo nano /etc/default/hostapd

# Old entry:
#DAEMON_CONF=""

# New entry:
DAEMON_CONF="/etc/hostapd/hostapd.conf"

This ensures the services start automatically when TorBox starts, and they also start immediately.

sudo systemctl unmask hostapd
sudo systemctl enable hostapd
sudo systemctl start hostapd
sudo systemctl unmask isc-dhcp-server
sudo systemctl enable isc-dhcp-server
sudo systemctl start isc-dhcp-server
sudo systemctl disable dhcpcd
sudo systemctl daemon-reload

• • •

8. Configuring Network Address Translation (NAT)

echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-ipforward.conf
sudo sysctl -p /etc/sysctl.d/99-ipforward.conf

# With the following command, we have to enable IP forwarding (necessary to overcom captive portals):
sudo sh -c "echo 1 > /proc/sys/net/ipv4/ip_forward"

• • •

9. Configuring Nginx to work with WebSSH and Onion Services

The default Nginx configuration works fine, but we need to allow uploads larger than 1 MB. Setting client_max_body_size to 0 removes the size limit. Of course, there is also the possibility of setting another, bigger size limit than 1 Mb. For security reasons, we also recommend setting server_tokens to off to hide the Nginx server version on error pages.

# Edit /etc/nginx/nginx.conf:
sudo nano /etc/nginx/nginx.conf

# Old entries:
client_max_body_size 1m;

# New entry:
client_max_body_size 0;
server_tokens off;

Nginx also has an annoying behaviour: it doesn’t remove the socket files in /var/run during a restart or when closing down. When starting again, Nginx complains about these existing socket files. Currently, in TorBox, we handle this in the script by looking for unused socket files and deleting them. Nevertheless, we recommend implementing this change to the /etc/init.d/nginx, which is recommended here by using the following command:

sudo sed "s|STOP_SCHEDULE="${STOP_SCHEDULE:-QUIT/5/TERM/5/KILL/5}"|STOP_SCHEDULE="${STOP_SCHEDULE:-TERM/5/KILL/5}"|g" /etc/init.d/nginx

Also, we don’t need the example configuration and HTML file, but the configuration file for WebSSH:

sudo rm /etc/nginx/sites-enabled/default
sudo rm /etc/nginx/sites-available/default
sudo rm -r /var/www/html

# This is necessary for Nginx / TFS
sudo chown torbox:torbox /var/www

sudo cp etc/nginx/sites-available/sample-webssh.conf /etc/nginx/sites-available/webssh.conf
sudo ln -sf /etc/nginx/sites-available/webssh.conf /etc/nginx/sites-enabled/

• • •

10. Disable Bluetooth

For security reasons, we recommend disabling Bluetooth on your Raspberry Pi.

# Change your /boot/config.txt:
sudo nano /boot/firmware/config.txt

# Add to the end of /boot/firmware/config.txt:
dtoverlay=disable-bt

# NEW v.0.5.5: hciuart removed because it is not anymore used in the latest Raspberry Pi OS
# Run following command to disable the related services:
sudo systemctl stop bluetooth.service
sudo systemctl disable bluetooth.service
sudo systemctl mask bluetooth.service
sudo systemctl daemon-reload
sudo apt-get purge -y bluez bluez-firmware pi-bluetooth
sudo apt-get -y autoremove
sudo rfkill block bluetooth

You have to reboot your Raspberry Pi to apply the changes.

• • •

11. Update sudo setup

sudo printf "\n# Added by TorBox\ntorbox  ALL=(ALL) NOPASSWD: ALL\n" | sudo tee -a /etc/sudoers
sudo visudo -c

• • •

12. Stop logging, preparing for the first start and restarting the system

# Preparing the system for the first start (we don't need nginx running if not needed)
sudo systemctl stop nginx

# To start TACA (TorBox Automatic Countermeasure Actions), notices.log has to be present
sudo -u debian-tor touch /var/log/tor/notices.log
sudo chmod -R go-rwx /var/log/tor/notices.log

# Stop logging
sudo systemctl stop rsyslog
sudo systemctl disable rsyslog
sudo systemctl mask rsyslog
sudo systemctl stop systemd-journald-dev-log.socket
sudo systemctl stop systemd-journald-audit.socket
sudo systemctl stop systemd-journald.socket
sudo systemctl stop systemd-journald.service
sudo systemctl mask systemd-journald.service

# Remove log files and history
sudo rm /var/log/*
sudo journalctl --vacuum-size=1M
history -c

# This is not mandatory, but we recommend to start our image preparation script 
# (even if you don't make an image) to check the installation and perform some 
# routine cleaning tasks
cd /home/torbox/torbox
bash install/prepare_image.sh

# If you don't want to use our preparation script (prepare_image.sh) in TorBox 
# Menu's install folder, you have at least to set the right start trigger in torbox.run
# This is necessary for starting the "first use" configuration dialogue.
sudo sed -i "s/^FRESH_INSTALLED=.*/FRESH_INSTALLED=2/" /home/torbox/torbox/run/torbox.run

# Restart the system
sudo reboot

After restarting the system, connect your client to the new WiFi “TorBox055” (password: CHANGE-IT). Log into 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 or using TorBox mini). After seeing a welcome screen and answering initial questions during the first start-up, you see the TorBox Main Menu. Immediately change the default passwords (the associated entries are placed in the configuration sub-menu). Check if your data stream is routed through the Tor network: https://check.torproject.org

moko on TorBox v.0.5.5 – OpenVPN Update, 22 March 2026: “I love this project. Please keep it going.” Jun 11, 20:17
ke on TorBox v.0.5.5 – OpenVPN Update, 22 March 2026: “Does the raspberry pi or any other computer that torbox and torbox mini runs on reveal any data to the…” Apr 22, 07:48
ke on TorBox v.0.5.5 – OpenVPN Update, 22 March 2026: “Regarding torbox mini on a raspberry pi zero 2 w it is required that the computer you connect the rpi…” Apr 14, 10:57
ke on TorBox v.0.5.5 – OpenVPN Update, 22 March 2026: “Running torbox-mini-20260322-v055.img on a raspberry pi zero 2 w I have tested torbox mini on a new installed instance of…” Apr 11, 08:17
ke on TorBox v.0.5.5 – Debian 13 (Trixie) Update, 01 December 2025: “Please discard my previous comment. I once more installed torbox-mini-20251201-v055.img on a raspberry pi zero 2 w. Connected the rpi…” Apr 5, 19:28