Pi Relay Field Manual

Pi Relay is the easiest way to transform a Raspbery Pi into a relay powering the Tor network.

Pi Relay Prerequisites

In this section we'll get everything ready before installing Pi Relay.

Raspberry Pi

  • Download the Raspberry Pi Imager
  • Flash a microSD card with Raspberry Pi OS (64-bit)

Raspberry Pi Prerequisites


Prepping Your Pi

If you didn't know, your Raspberry Pi doesn't come with an operating system. Don't panic! We're going to install one now called Raspberry Pi OS.

1. Raspberry Pi Imager

Like a Macbook runs MacOS, and a Dell runs Windows, a Raspberry Pi runs Linux, which comes in many different flavors depending on your needs. Since we're using a Raspberry Pi, we'll use Raspberry Pi OS (64-bit), an operating system made just for the Pi. The Imager installs the operating system onto your microSD card, where we'll set up Hush Line. Download it from https://www.raspberrypi.com/software/.

Prep Your Card

2. Install Raspberry Pi OS

Open the Raspberry Pi Imager and click Choose OS > Raspberry Pi OS (other) > Raspberry Pi OS (64-Bit).

Insert your microSD card into your computer, and then click Choose Storage and select your card.

Before clicking Write, click on the Settings gear in the bottom right of the window. Configure the following settings:

  • Hostname = pirelay
  • Enable SSH with password authentication
  • User = operator
  • Set a strong password
  • Add wifi settings

Boot up and log in to Your Pi

3. Insert microSD Card

Take your SD card and insert it into your Raspberry Pi. You'll find the SD card slide on the bottom of the board, opposite the ethernet ports.

Plug the power supply into the device and let it boot up.

4. Log In

On a Mac, open Spotlight search by pressing CMD + Space. Enter "Terminal" and select the application with the same name.

Enter ssh operator@pirelay.local, and when prompted, enter the password you created in the second step.

5. Update your system

The last thing we need to do is to update our system. First, we'll give ourselves admin priviledges, then perform the update:

Enter sudo su, then apt update && apt -y dist-upgrade && apt -y autoremove.

🎉 That's it, you're ready to get started with Raspberry Pi!

Installing Pi Relay

Pi Relay is made for Raspberry Pi and uses an e-paper display to show real-time information about your relay's activity.

In this section we'll walk you through everything you need to get up and running.

Types of Relays

After the install script begins, you'll choose the kind of relay you want to configure. Making the right decision for your installation environment will be necessary.

How Tor Works

First, let's understand how Tor works before choosing the kind of relay to use. Tor offers online anonymity by hiding information about your digital footprint, including your IP address, browser size, and operating system.

Think back to your preschool days when you wanted to send a secret "I <3 U" note to a crush. You asked your bestie to deliver it, ensuring your crush remained clueless about the admirer. In this analogy, your friend acts as a relay for you. But instead of the note going from you to your bestie to your crush, it goes from you to three random volunteers around the world, who you don't know but will deliver the message.

Entry Relays

In your chain of three volunteers delivering your note, the first person is the entry relay. The Tor network itself chooses relays based on factors including stability and performance. The entry doesn't know the destination address.

Middle Relays

A middle relay is the second person in the chain. They don't know who you are, and they don't know who your crush is - they're simply a middle-person.

⭐️ If you operate a relay from home, you should only choose a middle relay.

Exit Relays

Exit relays are the last step in the chain, and will request the website on your behalf. They don't know who you are but know who your crush is. Operating an exit relay should take extra consideration and should never be operated from home.

Here's a real example of why you shouldn't operate an exit from home: back in 2019, Trump's Justice Department demanded 1.3 million IP addresses of the people who visited a Trump protest website. Why did they want the IP addresses? What if you never visited the site, but it looked like you did? Could you potentially get in trouble?

If you run an exit relay, it will appear that YOUR IP address is the one visiting the site.

So if the teacher catches you handing the note, it will look like it's from you.

Again, never operate an exit relay from home. Businesses and public institutions like libraries and universities - who can donate high-speed internet and have enough money to afford legal council if needed - should only consider this option.

Bridge Relays

Bridge relays are a special type of relay. Sometimes, the Tor Network can be blocked completely. When this happens, bridge relays are the ones who become the entry. You can share your bridge address for someone to plug into Tor Browser, or Tor can share it automatically for you.

This person is the silent helper who will step in if all else goes wrong. They'll ensure the note is discretely delivered.

Installing Pi Relay

Pi Relay is made for Raspberry Pi and uses an e-paper display to show real-time information about your relay's activity.

To start the installer, enter:

curl --proto '=https' --tlsv1.2 -sSfL https://install.pirelay.computer | bash

Choose Your Relay Type

After the install script begins, you'll choose the kind of relay you want to configure. Making the right decision for your installation environment will be necessary.

Before proceeding, read about the different kinds of relays.

For this guide, we'll choose a middle relay.

Configure Relay Information

You need to set a few variables before your relay can go online.

Relay Nickname

We automatically generate a nickname that looks like pirelay231009. Avoid using special characters, spaces, or long names if you change it.


Your relay needs a port to make itself available to pass information. You must also forward this port if you're running the relay from home. If you don't know how, search for your router's instructions.

We pre-fill this option with port 443, the port used for secure HTTPS web requests. The default port that Tor uses is 9001, but this can be easily blocked. To get around port censoring, we chose 443 because blocking this would mean blocking much of the internet.

Monthly Bandwidth Quota

This is your "accounting max". To make it easy, we set this up as a monthly quota. Middle relays are required to share a minimum of 200 GB per month.

Bandwidth Limits

You'll set your bandwidth limit and burst rates. Tor recommends at least 2 MB/s, with a 4 MB/s burst. These values are entered by default for you.

Contact Info

You can optionally add your name and email address so Tor can notify you if your relay ever goes down. There's a default value entered for you, but consider adding an address you have access to.

Using Pi Relay

Once Pi Relay is running, you don't have to do anything! Since you have an e-paper display, you can check in on its activity to see how much bandwidth you've donated.

Automatic Updates

One of the tricky things about operating a relay is keeping it up-to-date. We handle this for you by automatically updating your device. You'll be able to see the Tor version on the diaplay to confirm it's working.


At first, you'll notice "No flags yet." After it's running for some time flags like "Running," "Valid," "Stable," or "Fast" will begin to display.

Bar Chart

You'll see a bar chart visualizing your bandwidth contributions relative to your monthly quota. Your display refreshes every minute, so you always know your most recent activity.

Hush Line's Features

1. PGP Email Encryption

To enhance the security of communications, Hush Line integrates the PGP (Pretty Good Privacy) protocol. This ensures that every email message is encrypted, offering a secure channel even if the message's content becomes intercepted.

2. Simple, Guided Setup

Ease of setup is paramount, and Hush Line’s installation script automates the configuration process. From package installations to system settings, the script takes care of the nuances, ensuring a hassle-free experience.

3. Tor-Ready

For users who prioritize anonymity, Hush Line is equipped to function seamlessly over the Tor network. Upon setup, a hidden Tor service is established, directing traffic to the local server. This provides an onion address, allowing users to access the platform anonymously.

4. Automatic HTTPS Certificates

With cyber threats on the rise, secure connections are crucial. Hush Line integrates certbot, automatically fetching and installing HTTPS certificates. This ensures encrypted communication between the user's browser and the Hush Line server.

5. Intrusion Detection

Hush Line integrates Fail2Ban, an intrusion prevention tool, designed to scan log files for malicious activity. If any is detected, fail2ban imposes a temporary ban on the suspicious IP, thereby fortifying the platform against brute-force attacks.

6. Firewall

The Uncomplicated Firewall (UFW) is incorporated into Hush Line's framework. This firewall tool simplifies the process of managing iptables, ensuring that only approved traffic can access the server.

7. Automatic Updates

Outdated systems are a breeding ground for vulnerabilities. Hush Line leverages the unattended-upgrades package to automate system updates. This ensures that the system always runs the latest security patches and software versions.

8. IP Address Scrubbing

Respecting user privacy, Hush Line has provisions to scrub IP addresses from incoming requests. This means that user location and network information are not stored or logged, enhancing user anonymity.

9. Hardened Nginx Security Headers

The platform is served using nginx, and the server is configured with security-hardened headers. These headers protect users from various web vulnerabilities like cross-site scripting and clickjacking, ensuring a secure browsing experience.

10. No Account Needed

Emphasizing ease of use and privacy, Hush Line eliminates the need for account creation. Users can immediately start messaging without the burden of sign-ups or the risk of personal data storage.

11. New Censorship-Resistance Research

Hush Line configures a sauteed onions domain when deploying to a public website like a .com, .org, etc. Sauteed Onions is a new method for making your onion address more censorship resistant by binding it to your domain name using HTTPS certificates, creating a new domain that looks like: addressforyouronion.acme.com. Now, when someone uses a certificate search tool like crt.sh and looks for your domain name, they'll find your onion address, too.

More Resources


Hush Line site: The website that your Hush Line form is available at. If you're running Hush Line in "Tor-only" mode, your Hush Line site will have a URL like http://vfalkrrucjb7pztjskfumnqytpze5iimu4i2t2ygwv6ntylvylt2flad.onion and will be only accessible through the Tor Browser.

Hush Line form: The text box form that occupies your Hush Line site. Community members may choose to type and submit a message through this form (thus becoming a source).

community: The pool of people who know your Hush Line site's URL. If you only share your Hush Line site's URL with a team of employees, that's your community. If you promote your Hush Line address publicly, your community may be very large.

community member: A member of your community. A person who is a potential source.

source: The community member who has written and submitted a given message

message: The text that a source submits to your Hush Line form. Hush Line only accepts text messages (no multimedia or file attachments). All Hush Line messages are encrypted and thus private. Also note that Hush Line messages only go one-way: from source to user.

Hush Line user: The person who runs the Hush Line. We assume the user has access to the Hush Line email address and Hush Line PGP key.

Hush Line email address: The email address that receives your Hush Line messages from your sources

Hush Line PGP Public Key: The PGP public key that Hushline uses to encrypt all messages before sending emails to your Hush Line email address.

Hush Line PGP Private Key: The private PGP key the user uses to decrypt Hush Line messages. The PGP password is also needed to decrypt messages.

Hush Line PGP password: The password needed, in combination with the Hush Line PGP Private Key, to decrypt and read messages. (Keep this secret.)