Skip to content

Welcome to the Matrix: Your Tor real-time chat onboarding guide

Matrix keeps us connected. It is where teams coordinate, where questions get answered, and where we argue about cake versus pie. It is also where we ask questions internally across teams. It is how we engage externally with volunteers, how our engineering teams collaborate, and how we share the day’s cutest pet pictures or funniest links. This guide will take you from zero to fully plugged into Tor’s Matrix spaces.

What this guide will help you do

  • Understand what Matrix is
  • Install Element, our recommended Matrix app
  • Create or use a Matrix account
  • Join the Tor Public Space
  • Join the Tor Internal Space for staff communications
  • Adjust a few important settings to make your experience smooth

What is Matrix?

Matrix is a free software, encrypted, decentralized chat platform. You can think of it as Slack, if you have used that before, but with more freedom, encryption and privacy.

A Matrix account lets you talk privately with individual people, join rooms where you can talk with groups of people, and join Spaces which are groups of related rooms.

We have a Tor Space, which contains all of our Rooms, some of which are public, and some of which are internal. Rooms are used for topics, teams, work coordination, and general chat.

Step 1: Install Element

Element is the most user-friendly Matrix app. Choose whichever version you prefer:

  • Desktop: Windows, macOS, Linux
  • Mobile: iOS, Android

Download page: https://element.io/download

Step 2: Create or sign in to a Matrix account

If you already have a Matrix account, go ahead and sign in. Make sure you have a backup of your "Recovery key".

If you do not:

  1. open the Element app either after downloading it or through the app.element.io web interface. we will assume you use the web interface here.

  2. click "Create account" then "Continue" when prompted for matrix.org

  3. pick a username that matches your existing Tor user as much as possible. your visible username can be different, this is your login. then "Continue with email address"

  4. set a strong, random password, and store it in your password manager

  5. enter your @torproject.org email address

  6. agree to terms, fill in the CAPTCHA and hit "Continue"

  7. this will send a token to the email address, check your email and enter the token

  8. pick a "display name": this can be different from your login and will be what is most visible to users in chats

  9. at this point, you should be logged in to the Element client

  10. go to the "all settings" dialog by clicking on your avatar on the top left and go in the "Encryption" section to set the recovery key, add it to your password manager

Your Matrix ID will look like:

@username:matrix.org

That is your address in the Matrix world.

Step 3: Join the Tor Project Space

The Tor Project Space is where you join to participate in discussions. Many rooms include volunteers, researchers, and community members from around the world. Treat it as a collaborative public square.

In Element, select + Explore or Join a Space

Enter this space address: #tor-space:matrix.org

Open the space and click Join

Once inside, you can explore rooms, these are public rooms. Try joining the "Tor Project" room - this is a general, non-techical space for discussions about The Tor Project with the broader community. Feel free to say hi!

Step 4: Join the Tor Internal Space

Internal rooms are only for Tor staff core contributors. This is where work discussions happen and where we can have slightly more private conversations.

To join: let your onboarding buddy, team lead, know your Matrix ID. They will add you to the Tor Internal Space (currently by asking TPA) and team-specific rooms

Join the "Cake or Pie" channel and tell people there which you prefer. This is where Tor-only folks go to chat, like a watercooler of a bunch of friendly Tor people.

Once you are in, you can:

  • Use @mentions to reach teammates
  • Chat with folks in channels
  • Send private messages to individuals
  • Create your own team channels

If you do not see the right rooms (your team’s channels, etc.), ask! No one expects you to know where everything lives.

Step 5: Helpful Setup Tweaks

A few quick improvements for maximum sanity:

  • Enable notifications for mentions and replies
  • Set your display name to a recognizable form so people can remember who you are
  • Set a profile picture to whatever you'd like

Where to Ask for Help

You will never be alone in this city. If you run into any trouble:

  • Contact your team lead
  • Ask in the #onboarding room (if available)
  • Ping the TPA team
  • Ask your onboarding buddy

You are connected! You are now part of our communication backbone. Welcome to Tor. We are glad you are here. For real.