Tephro · Guides

Using Tephro

The member's guide: joining a server, chatting, talking, sharing your screen, and what the client keeps on your machine. Running a server is a separate guide, HOSTING.md.

Install the client

Download the client for your platform from the releases page — on Linux the AppImage (chmod +x, run it), the .deb, or the .rpm (Fedora, openSUSE); on Windows the installer. Nothing else to install. Arch users: the release carries a .pkg.tar.zst for pacman -U (it is not on the AUR). Unsigned builds show the usual unknown-publisher warning until code signing lands; the SHA256SUMS file on the release page is how to check what you downloaded.

When a new release is out, the update button at the bottom of the left rail gets a dot. Click it: Update now downloads the release, checks its signature and restarts; Later leaves the dot and asks nothing. If you installed from a package, the dialog shows the command to run instead.

The client opens on the home screen: one card per server you have joined, and an Add a server card. A fresh install has only the add card.

Join a server

Whoever runs the server gives you an invite, normally a link that starts with tephro://. Click it, or paste it into Add a server — it fills in the address, the server's certificate fingerprint and your invite key, and the client shows the connection as verified. If you were given only an address, switch to Enter the details manually: address, the certificate fingerprint if you have it, and an invite key. Without a fingerprint the client shows the one it sees and marks the connection as trusted on first sight — ask the operator to confirm it matches before you register. The same form reopens, prefilled, from Edit connection in the server's settings, where the port can be changed: if the operator moved the server to a new port, change it there and the client reconnects with the same account and key. Pasting a new link for a server you already have on another port asks whether to move the connection or add it as a separate server.

Registering creates your account on that server only. The client generates a key pair for it; the private half never leaves your machine, and the server holds only the public half. There is no password unless you add one as a second lock (below). A username and display name are yours to pick and change; the general profile in Settings is a default the client offers when you join somewhere new, not an identity — every server sees a separate account. A picture may be an animated GIF or WebP: it stays still in lists and moves only while you speak in voice or someone has your profile card open, and it must fit the server's size limit or a still frame is uploaded instead. Everything else that moves (GIFs in chat, custom emoji, a server's icon and banner) plays while the Tephro window has focus and pauses when you switch away. The system's reduce-motion setting stops all of it.

Some servers approve members by hand, and a link that was posted publicly usually puts you in that queue while a key made just for you lets you straight in. Either way you see a waiting screen after registering, not an error, until an administrator lets you in.

Inside a server, the top of the channel list shows its banner, icon, name and the operator's message of the day. Click your own name at the bottom to set how you appear: Online, Away, Do not disturb (mentions arrive silently), or Invisible (offline to everyone; the server honours it). The choice is per server and per computer.

Text

Channels are on the left; click one to read and type. @name mentions someone, Enter sends, Shift+Enter makes a new line. The composer takes files by the + button, drag-and-drop or paste, up to the server's size limit; images, audio and video show inline, everything else as a download.

• Emoji: the smiley button opens a picker, or type : and a few letters to autocomplete. Servers can add their own custom emoji; they appear in the same picker.
• Reactions: hover a message for the react button, or click an existing reaction to add yours.
• Reply quotes a message above yours and notifies its author. Forward sends a copy to another channel.
• Links are clickable and get a preview. The server fetches the preview, not your computer, so the site never sees your address. A link to a picture or a short loop draws in place; a loop plays muted while the window has focus. A link to a video file is a player with sound that starts when you click it.
• Videos and posts from the large platforms (YouTube, Vimeo, Dailymotion, Streamable, Odysee, Rumble, TikTok, Twitch, X, Reddit, Instagram, Facebook) show as a card with a play mark. Nothing is loaded from the platform until you click. After the click the platform's own player runs inside the message, and from then on that platform sees your address, as it would in a browser. Some videos a platform will only play on its own site; the line under the player opens the link in your browser.
• Hide a preview with the × beside it; the link stays. Show preview brings it back. It changes your view only, on this device.
• Edit and delete your own messages from the hover buttons. Moderators can delete anyone's.
• Search (the box at the top) finds words in every channel you can see, or just the one you are in; the last word matches as you type, and accents do not matter. Click a result to jump to it; from there, scrolling loads older messages above and newer ones below until you are back at the present, and Jump to present is the shortcut. In a direct message the search runs on your own computer over the messages it holds, because the server cannot read them.
• Pins: a moderator can pin a message from its menu; the pin button in the channel header lists a channel's pins, and clicking one jumps to it. Bookmarks are pins for you alone, kept on this computer: the bookmark button beside it lists them. The threads button next to those lists the channel's threads.
• Videos arrive as a blurred first frame with a play button and download only when you click, so a busy channel does not fill your disk; Settings → Video → Auto-download videos fetches them as they come. Before you send one, the composer shows the same frame so you can check it is the right file.
• Threads: Reply in thread on a message opens a side panel where the conversation continues without filling the channel; the message shows how many replies it has and when the last one came. Replies do not count as unread, but a mention inside one does, and clicking it opens the thread. Deleting the first message deletes the whole thread. Direct messages have no threads.
• Notifications are yours to shape, per server, on this computer. Each channel has a level from its menu or the bell in its header: mentions (the default: you or @everyone), all messages, or mute (nothing, and no unread marker — a mention still shows its count). Settings → Notifications takes keywords; a message that contains one is announced and highlighted like a mention. Keywords in code or behind a spoiler do not count.

Formatting

Messages take a small, fixed markdown: enough for structure, never a page layout. The same rules apply in direct messages.

Two more use the vertical bar, which this page's own table cannot show: two bars on each side of a word hide it as a spoiler until the reader clicks it, and rows of bar-separated cells with a line of --- cells under the first make a table, up to six columns and twenty rows.

Anything else is plain text: no images by markdown, no HTML, no underline, no horizontal rules, nothing nested deeper than one level. Put a backslash before a character to keep it literal (\*, \|, \#) — a line that starts with * or - is a bullet unless you do.

A video the client cannot play — most often HEVC from a phone — says so and offers the download.

Your tag. The short label beside your name comes from a list the whole server shares: pick one, or add a new one and others can pick it too. Administrators can rename, merge or remove entries, which changes it for everyone carrying it.

Direct messages

Hover a member and choose Message, or open an existing conversation under Direct messages in the sidebar. DMs are end-to-end encrypted between your devices and theirs: the server passes them along and keeps only the encrypted form, so an operator can see that you talked and when, never what you said.

Two consequences worth knowing. Encryption is per device, so a device you add later cannot read messages that were sent before it existed (a backup restores a device's keys, see Your data). And DMs are per server — the same person on another server is, to the client, another person.

A direct message works like a channel: edit and delete your own messages, reply, react, forward (into another conversation or a channel), attach files, and paste links — the preview card is made by your client and travels sealed with the message, so the other side never touches the link. Pins and mute in a DM are yours alone: they live on this device, and a muted conversation still counts unread.

Close in the conversation's header hides it and drops its history on this device only; the other person is not told, and their next message brings it back. Block on a member's row stops conversations in both directions; unblock from the same place.

Voice

Click a voice channel to join it. The footer at the bottom of the channel list shows the channel you are in, how good the connection is and the level your microphone is sending, with the mute, deafen, camera and share buttons. Click or right-click anyone — in the member list or in a voice channel — for their volume slider (up to 200 %, which is a real +12 dB, with a limiter so nobody clips), a mute that only you hear, a direct message, block, Favorite, which keeps them at the top of the member list, and Watch stream when they are sharing. You can join a voice channel without a microphone: the footer says listening only and offers a retry, and plugging one in is picked up by itself.

• Devices (Settings → Audio): pick the microphone and the output, test the microphone with the level meter, and Hear yourself to check how you sound through the chosen suppression. Echo cancellation and automatic gain are on by default; both can be switched off for a microphone that does its own.
• Microphone boost (Settings → Audio): 100–300 %, applied before noise suppression and after your operating system's level — raise that first, use this for a microphone that is quiet even at full.
• Echo: the client cancels it; headphones still help everyone.
• Noise suppression (Settings → Audio): a choice of models. The default cleans keyboards and background voices well; switch mid-call if one suits your microphone better.
• Push-to-talk (Settings → Audio): on, your microphone is open only while the key is held. On Windows and X11 the client can grab a global hotkey. On Wayland it cannot, by design, so instead bind a key in your compositor to the small tephroctl helper that ships beside the client — tephroctl ptt on on press, tephroctl ptt off on release (Hyprland and sway support both; GNOME and KDE shortcuts are press-only, so use tephroctl ptt toggle). Anything that can run a command works: stream decks, macro pads, foot pedals.
• Voice sensitivity (Settings → Audio): the level below which you count as silent. Others see the speaking ring only above it and nothing quieter is sent. The default suits a quiet room; move it towards −20 dB in a noisy one, towards −80 for a soft voice. The marker on the mic-test meter shows where it sits.
• Sounds (Settings → Audio): soft two-note cues when someone joins or leaves your voice channel, when you mute or unmute, and when a message would notify you. They are generated inside the client — nothing is downloaded, and nobody else hears them. A toggle, a volume slider, and a picker to hear each one.
• Connection details (the ⓘ button on the voice bar) shows how you are connected and, when something is wrong, one sentence saying what. Voice normally uses UDP on port 443; if your network blocks that, it falls back to TCP on the same port by itself.

Camera and screen sharing

In a voice channel, the camera and share buttons publish to the room. Click any tile to focus it: it fills the view and the rest line up along the top; click a small one to switch, click the big one or press Escape to go back to the grid, double-click for fullscreen. Settings → Video picks the camera and its resolution, with a live preview, and the frame rate a screen share sends. Other members see a closed tile with a Watch button: nothing streams to you until you open it, and closing it stops that stream from being sent to you at all, which is how a call stays light on slow connections. The ⓘ on any tile shows what is actually flowing: resolution, frames per second, kilobits per second, the codec, and on your own tile each layer you are sending. Every camera and screen tile has a quality picker, and its entries are the pictures the sharer actually sends, named by size, frame rate and bitrate: 1080p60 · 5.0 Mbit/s, 1080p30, 720p30, 480p15. When a tile opens it samples your connection for three seconds and settles on one; after that nothing changes it but you. A tile that keeps dropping frames says so once and leaves the choice to you. The choice lasts for the call.

Sharing a screen or a window first shows what you will send, on every desktop: a resolution cap, the frame rate (60 by default), a bitrate ceiling (auto names the number it will use, or pick one — 8 Mbit/s means 8), sharp text or smooth motion (what to keep when the encoder is pressed), the codec (Auto is VP8 for a screen and VP9 for a camera; AV1 saves upload and costs your CPU; an entry the server disallows is greyed out), and whether to also send lower rungs so viewers can pick a smaller picture (about 40 % more upload). Then the desktop's own picker opens on Wayland, or the client's list elsewhere. The camera asks the same way. The server never re-encodes, so what you send is what they get, and the same fields sit on your own tile's pill during the share and under Settings → Video. When you share, you can also pick which applications' audio goes with it — a game but not your music, never the call itself. On a Mac there is no audio capture without a virtual audio device such as BlackHole. On Wayland a blue-light filter (KDE Night Color, GNOME Night Light, f.lux) is captured with the screen, so your viewers see the tint: pause it while you share.

Any tile can be popped out into a window of its own — the ⧉ button on the tile — a bare window with nothing but the picture, which you can move to another monitor, resize or fullscreen (double-click; Escape closes it). It keeps playing while you look at a text channel or minimize the main window. The sound still comes from the main window. The ⓘ on a focused tile shows the stream's numbers inline beside the buttons instead of a box over the picture, and the signal bars in the voice bar are the button for the connection details.

A second lock on your account

Your key is what signs you in. If you want a stolen key file to be useless without something more, Settings → Account → Second factor adds a password, an authenticator app (Aegis, or any app that scans a QR code), or both; from then on a new sign-in asks for them after the key. The authenticator is the stronger of the two: a keylogger on the computer that holds your key never sees your phone. There is no reset. If you lose the phone or forget the password, an administrator's recovery code gets you back in and clears both, and you set them up again.

Adding a device

On the new computer, add the server as usual and pick Link to an existing account: it shows a short code. On a computer where you are already signed in, open Settings → Devices, choose Link a device and type the code. A moment later the new device names the account it was linked to and asks you to sign in — check that it is yours. The code is not a secret, only a name for the new device's key: whoever types it first attaches that key to their account, so if the name shown is not yours, someone else got there first; choose Not my account and the key is thrown away unused. Every device you are signed in on is told when a device is added, so a link you did not make is something to act on: remove the device in Settings → Devices. The code is good for ten minutes and once.

Your data

Everything the client stores is under one folder: ~/.local/share/tephro/client on Linux, %LOCALAPPDATA%\Tephro\client on Windows, ~/Library/Application Support/Tephro/client on macOS. Your keys are sealed with the operating system's keychain; Settings → Keystore passphrase adds a passphrase over that, asked once at start.

Back up (Settings → Backup) exports one encrypted file holding your general profile and your keys for every server, DM keys included. Restore it on a new machine to get your accounts back. There is no password reset: if everything is lost, an administrator's recovery code gets you back in and clears the old keys along with any second lock you had set.

Devices: an account may hold two keys, so a second machine can be added — by the code in Adding a device, or from Settings → Devices by pasting the new machine's public key on the one that already has access. Only one live session per key: if a copied key ever connects elsewhere, the collision tells you.

Leave a server from its card on the home screen. Your messages stay, under your old name, so conversations still make sense to the people who were in them. Being removed by a moderator is the same departure, done for you.

What the client keeps on disk, file by file, is in YOUR-DATA.md.

When something is wrong

Disconnected, timed out, removed or banned? The client tells you which, with the moderator's reason when they gave one. Disconnected: connect again whenever you like, nothing about your account changed. Timed out: the server card shows a countdown, and you are back in when it ends. Removed: your account on that server is gone and the card with it; a new invite from someone there lets you back in — the same client, the same key, a fresh account. Banned: the card goes and there is no way back. A moderator can also time you out from voice alone, or move you to the AFK channel, where nobody hears or sees anyone until they leave it; text keeps working in both cases. Sit silent in a voice channel for ten minutes (muted counts) and the server parks you in the AFK channel by itself and shows you as away; leave it and your own status comes back. You cannot start a camera or a screen share from the AFK channel, and a running one ends when you are moved there. While you are in a call, the chat button at the top of the voice view shows a text channel beside it, in place of the member list; the two share that space. The channel is the one you looked at last, and the picker in its head switches.

The client keeps a log on your machine — Settings (the cog at the bottom of the rail) → Storage → Log file, with Open folder and Copy path. It stays on your computer, is capped at a few megabytes, and holds no messages or keys. When you report a problem, send that file along with what you did.

• Trusted on first sight on a server you expected to be verified: the link you were given had no fingerprint, or the server's certificate changed. Ask the operator.
• Can't hear anyone or nobody hears you: open Connection details. If it names UDP, the operator's port forwarding or firewall is the usual cause; if it says TCP fallback, your own network blocks UDP and voice will work with a little more delay.
• Screen share shows nothing on Wayland: the desktop's portal was cancelled or is not installed (xdg-desktop-portal plus the backend for your desktop).
• A DM shows sent before this device existed: expected on a newly added device; restore the backup from the old one to read history.