# onboarding friends and family to matrix
The first post on this site makes a claim I still believe: most people are not going to rent a VPS and maintain a Synapse install just to chat with their friends. What that post skipped is the other side of the deal. If you run the server so nobody else has to, you also become the person who explains the server. The pitch takes one conversation. The onboarding takes months, and it happens in kitchens and over the phone, not in a terminal.
I have done this a few times now. Here is the friction list, roughly in the order it shows up, plus the things I stopped explaining somewhere along the way.
Getting anyone interested at all
Before the client question comes a harder one: how do you make someone care about a messenger? Short answer: you mostly don’t, not on a schedule. Nobody switches chat apps because they lost an argument. They switch when their current app does something they hate, and your job is to be the person who already has an answer on that day.
Things that have actually produced curiosity here:
Lead with what their app cannot do, not with privacy. “Same account on phone and laptop.” “I can join the call from a browser tab, nothing installed.” “The group is ours, not the platform’s.” Privacy is a reason to agree. It is rarely a reason to ask a follow-up question. A concrete difference is.
Show, don’t pitch. The demo that works takes thirty seconds: your account and an account on some other server, talking in the same room, and the moment where someone goes “wait, nobody owns this?” That moment is worth more than any speech about encryption.
Answer the question asked, then stop. The fastest way to kill interest is the follow-up lecture. If they ask “is it like WhatsApp?”, the answer is “yes, but nobody owns it”, and then silence does the rest. Every time I pitched for twenty minutes instead of thirty seconds, I got a polite nod and nothing else.
Do not sell while they are happy. The window to mention Matrix is not when everything works. It is the week the app redesigns itself into something they hate, the group fights about a new policy, or someone gets locked out of their account. When the current tool lets them down, “I have something for that” sounds like help instead of homework.
Accept the ratio. For every person who asks a follow-up question, nine nod politely and keep scrolling. That is not failure, that is the funnel. You are not recruiting, you are leaving a door open. The one in ten who comes back months later with “that thing you mentioned…” is who the rest of this post is for.
“Which client do I install?”
This is always the first question, and the honest answer is: pick one for them. Handing someone a list of ten clients when they asked for one app is not helpful, it is a new decision they did not ask for.
My default for people on salix.host is Element. On the phone, Element X. On the desktop, the web client at chat.salix.host, no install needed. That is the whole answer. If someone later finds Element too busy and wants something calmer, I mention that I also host Cinny and they can switch whenever they like, same account, same rooms. But that conversation comes later. Day one, there is one app.
The mistake I made early was explaining the client ecosystem. “There are lots of clients, because it’s an open protocol, so you can pick…” Nobody has ever cared. The open protocol is why they can switch later. It is not a selling point at the door.
“Why do I have to pick a server?”
One sentence, using email: “your address is you@salix.host the same way your mail is you@gmail.com, I run the salix.host part, and it can talk to every other server.” People nod, and that is the entire lesson. It genuinely is enough.
The trap is continuing. Federation, homeservers, room state, why some rooms show a padlock: all interesting, none of it needed to send a message. The email analogy holds up for everything a normal person will actually do, and by the time it breaks down they will have used Matrix long enough that the detail will not scare them.
Verification
Sooner or later an unverified session warning appears, and people assume they did something wrong. The line I use: “the app is asking whether you’re you. Tap yes.”
That is the entire explanation now. I used to try to explain device keys and cross-signing, and I watched the eyes glaze over in real time. Nobody has ever asked a follow-up question about verification. They ask “did I do it right?” and the answer is yes.
The recovery key
This is the talk that matters, and it happens before anything else, ideally during signup.
With end-to-end encryption there is no “forgot password” that brings your history back. The recovery key is the only thing that gets your old messages onto a new phone. So: write it on paper. Not in the notes app on the phone that will eventually go through the washing machine. Paper, drawer, done.
The talk costs two minutes. Skipping it costs one lost phone and an afternoon of explaining why the photos are gone. I have been on both sides of that conversation, and only one of them ends with the person still using Matrix.
Notifications
The complaint that arrives by text a week later: “I don’t think this works, I don’t get anything.”
Nine times out of ten, on Android, the cause is the battery optimizer, not Matrix. The phone is quietly killing the app in the background to save three percent battery. The fix is going into settings and telling the phone to leave the app alone. On iPhones this is not a problem, which is unfair, but there it is.
Worth knowing in advance, because “the app is broken” is the story people tell themselves, and once they believe it they stop opening the app. One settings visit, done.
Bridges
Sooner or later someone asks: “can I use this to message my friends on WhatsApp?”
The technically true answer is that bridges exist. The honest answer is do not build on them. They break, they lag, and the person on the other side never agreed to any of it. They are still on WhatsApp, they just cannot see it. A bridge keeps the old app exactly where it is, on the home screen, winning.
The goal was never a clever tunnel into someone else’s network. The goal is a place where the people you care about actually are. That means migrating a group, not tunneling into one.
What actually worked
Three things, and none of them are technical.
Doing it next to them. A signup link in a chat gets you nothing, nobody reads instructions, including you and me. Sitting next to someone for ten minutes gets them an account, a recovery key on paper, and a verified session before they leave the room.
One real group, not the whole address book. The family chat was the unit that mattered. One person with a Matrix account and nobody to talk to is just a person with a new app they will delete in a week. One group that moved means every member has a reason to open it.
A reason with a date on it. A trip, a party to plan, a pile of photos to share. A messenger switch sticks when there is something to talk about this month. “For privacy” is a reason to agree. “The trip photos go in this room” is a reason to open the app.
What I stopped explaining
Federation beyond “like email”. Cross-signing. Why rooms have keys. What a homeserver is. Why there are two Elements.
The whole curriculum is now three sentences: “It’s like email.” “Tap yes, it’s you.” “Write this on paper.” Everything else is for people who ask, and almost nobody asks. The ones who get curious about the protocol will find their way to a post like this one.
And that is fine. The point was never that my family understands Matrix. The point is that the group chat where the dog photos happen now runs on a server where the admin knows the dog’s name. It took months, one person at a time, and it is the part of running this server I am proudest of.
~$