Tephro · Guides
Privacy
Tephro sends nothing to us. No telemetry, no analytics, no crash reports, no account with us. We run no central service, so we never see your messages, your servers or you.
Your chats live on the servers you join, and whoever runs a server holds its channel messages. Direct messages are end-to-end encrypted.
Tephro only contacts your own servers, plus these if you use them:
- Update check: off until you turn it on, or click the update button. It reads GitLab's public list of releases and carries nothing about you.
- Our repository: if you add it, your system checks tephro.chat for new versions. The host sees your IP address.
- Link previews: fetched by the server in channels, and by the sender in direct messages.
- Video cards: your client loads a platform's player when you click play.
- Detect my public IP: a button a server operator may press once.
Where it all lives
Everything Tephro writes lives under one folder, so you can find it, back it up, move it or delete it in one motion. Nothing goes to the registry, to ~/.config, to ~/.cache, or next to the program. This page lists every file and folder under that root, what is in it, and what is never stored anywhere.
| Platform | The root |
|---|---|
| Linux | ~/.local/share/tephro (or $XDG_DATA_HOME/tephro if you set that) |
| Windows | %LOCALAPPDATA%\Tephro — local, not roaming, so browser caches never follow a roaming profile |
| macOS | ~/Library/Application Support/Tephro |
Setting TEPHRO_HOME moves the whole root, for both halves below.
On Windows there is one more folder, and it is the installer's rather than Tephro's: the program itself lives under %LOCALAPPDATA%\Programs, with a Start-menu shortcut and the usual uninstall entry. Updates replace that folder; uninstalling removes it and leaves your data under %LOCALAPPDATA%\Tephro for you to keep or delete.
The root holds up to two folders: client/ if you use the desktop app, server/ if you run a server. Most people have only the first. Inside each, default/ holds everything; a second profile or server sits beside it in a folder of its own name.
client/ — the desktop app
Everything the app keeps is in client/default/; a second identity started with --profile <name> has a folder of that name beside it, holding the same files.
| What | Where | What is in it |
|---|---|---|
| Your keys | client/default/secure.json | The one file that matters. One key pair per server you have joined (never shared between servers, so nobody can link your accounts), your DM keys and the key your DM history is sealed with, the device keys of other members you have seen and which ones you confirmed or verified, your session tokens, your general profile (the default name and picture the app prefills when you register somewhere), the list of servers on your home screen, and the things each server never learns: favorites, local mutes and volumes, bookmarks, notification rules, panel widths, closed conversations, closed mentions and join rows in the notification column, which groups you folded in each server's sidebar and in that column, the emoji picker's recent picks, folded groups and source button, what your connection carried on the last screen share it limited (one number per server, used to pick your default bitrate), the pins and searches in your DMs. Every value is sealed with the operating system's keychain (values start enc:); Settings → Keystore passphrase adds a passphrase over that. On a desktop with no keychain (a bare window manager without GNOME Keyring or KWallet) values are stored unencrypted (they start plain:, base64 of the clear text), so the client asks once, after the first sign-in, for a passphrase there, and offers a backup in the same step. Without a keychain or a passphrase, a copy of this file is everything: your keys, and the session tokens that keep you signed in without asking for 2FA again |
| Server certificates you trust | client/default/pins.json | The fingerprint of each server's TLS certificate as you first saw it (or as the invite link stated it). If a server's certificate ever changes, the app refuses to connect until you look |
| Window behaviour | client/default/desktop.json | What closing the window does (quit, tray, ask), how often the app checks for a release on its own, hardware acceleration, enhanced logging, the GPU priority while sharing (Windows), and which of the Tephro chat's entries (welcome, what changed after an update, a release on offer) you have opened |
| Your direct messages | client/default/dms/<server>/ | This device's history of every conversation on that server: one file per conversation (<id>.log), each line sealed under a key kept in secure.json, and the files sent in them under files/, still encrypted as they were sent. Servers keep a direct message only until your devices have it, so this is your copy. Settings → Storage → Keep messages sets how long (forever, 1 year, 90 or 30 days); deleting history is permanent. Removing a server from this client removes its folder. A backup carries the key, never the history |
| Your collection of custom emoji | client/default/collection/ | Every emoji you added from the picker or from a message: one file each under emoji/, named by its fingerprint, and index.json with the names you gave them (and the other name one goes by on a server where its own was taken). It never syncs between devices, and no server has it until you post one there. Right click in the picker removes one |
| Pictures the home screen needs offline | client/default/imagecache/ | Server icons and banners, one file each, named by a hash. Settings → Storage → Clear cache empties it; the app refetches when you connect |
| The application menu entry (Linux) | ~/.local/share/applications/tephro.desktop, its icon client/default/tephro.png | Only when you press Create in Settings → Desktop; Delete removes both. It starts the copy of Tephro you created it from; Update re-points it after you move or reinstall. Uninstalling an AppImage removes it with it |
| Link-preview pictures and videos | client/default/previewcache/ | The picture or short video of each link preview you have scrolled past, one file each, named by a hash, with its kind, the platform it came from and the server it was on, so it is not downloaded from the server again. At most 500 MB: past that, the ones unseen longest are deleted, and the server still has them. Settings → Storage → Clear cache empties it |
| The log | client/default/logs/client.log, client.log.1, client.log.2 | What the app did, for bug reports: start lines with versions, errors, connection events, and since 2026-09-18 what you did (which channel, which button, which tile) and what the app decided (a notification shown or held back, and why). With Enhanced logging on (the default), call and stream measurements every few seconds. Capped at 5 MB with two previous files kept, about 15 MB at most. Never holds your keys, tokens, invite keys, passwords, message text, the links in messages, file names, device names, your IP address or where the app is installed; your home folder is written as ~. Settings → Storage → Log file opens the folder. Every kind of line is listed in DEBUGLOG.md |
| How the last run ended | a line in client/default/logs/client.log, [shell] run record | When this run started, its version, and when it quit. A start that finds no quit time writes to the log that the run before it died. Deleting the logs makes the next start look like the first |
| Crash dumps | client/default/crashes/ | What Chromium writes when one of its processes crashes: the state of that process, which can hold what was on screen. The newest five are kept. Never sent anywhere: there is no address to send them to. Delete the folder whenever you like; attach a dump to a bug report only if you choose to |
| A second identity on the same desktop | client/<name>/ | Everything above, once more, beside default/, when you start the app with --profile <name> |
| The browser engine's own files | client/default/Cache/, client/default/GPUCache/, client/default/Local Storage/, client/default/Session Storage/, and a few sibling folders | Chromium's caches, GPU shader cache and window-state scraps. Safe to delete while the app is closed; the app recreates them |
Two things live outside the root, briefly:
- **
$XDG_RUNTIME_DIR/tephro.sock** (Linux;\\.\pipe\tephroon Windows) — the tiny control socket thetephroctlhelper talks to for push-to-talk from a compositor keybind. It exists only while the app runs and is owned by you alone. - The OS temp folder — a downloaded installer, while update-on-click runs it. An AppImage replaces itself in place instead and needs no temp file.
And one thing goes wherever you point a save dialog: the app backup (Settings → App backup), one encrypted file holding your general profile, your settings and your keys for every server, DM keys included, but not your Collection, your DM history or this machine's devices. Restore it on a new machine to get your accounts back. Keep it somewhere safe: there is no password reset, because there is no email.
server/ — if you run a server
The data directory is the whole instance. Copy it and you have copied the server. It is server/default/; a second server on the same machine, started with --instance <name>, has a folder of that name beside it.
| What | Where | What is in it |
|---|---|---|
| Settings | server/default/tephro.toml | Every setting, commented. The status view's settings screen and tephro-server admin config set write this same file |
| The database | server/default/tephro.db (plus -wal and -shm while running; tephro.db.pre-<number> and tephro.db.post-<number>, copies of the database from before and after the latest upgrade changed its layout, and tephro.db.replaced after one was put back; removed after rollback_copy_days, 14 by default; until then they still hold what was deleted after they were taken, expired disappearing messages included) | Accounts (public keys only — the server never sees a private key), roles, channels, messages, read state, invites, the audit log. Direct messages are sealed and held only until every device they are for has them (at most dm_relay_days, 30 by default): the server relays ciphertext it cannot read and keeps no history |
| The certificate | server/default/tls/cert.pem and server/default/tls/key.pem | Generated once on the first run (ten years, self-signed); server/default/tls/acme/ when Let's Encrypt is used instead. The key file is readable by the server's user only; after tephro-server admin tls seal it is not in the folder at all but sealed in /etc/credstore.encrypted/tephro-<instance>-tls-key, which only systemd opens, for the service |
| Uploads | server/default/attachments/<id> | Every file members posted in channels |
| Uploads in progress | server/default/uploads/<id> | A large file still arriving in pieces. It moves to attachments/ when its last piece lands, and is deleted after a day with no new piece |
| Sealed DM files | server/default/dmfiles/<id> | Files sent in direct messages, encrypted by the sender; the server cannot open them, and holds each only until every device it is for has it, or dm_relay_days (30) passed |
| Removed, held for restore | server/default/held/<id> (and <id>.sound, <id>.poster) | Attachments and link-preview files a cull took, kept for cull_hold_days (7) so an admin can restore them, then deleted; early when the disk is nearly full |
| Pictures | server/default/avatars/<user id>, server/default/avatars/instance and instance-banner, server/default/emoji/<id>, server/default/embeds/<id> (and <id>.sound, <id>.poster) | Members' avatars, the instance icon and banner, custom emoji, and the pictures and short videos of link previews the server fetched. A .tmp or .fetch-* file beside one is a write in progress, and gone after it |
| Sounds | server/default/sounds/<id> | The soundboard's clips, Ogg Opus, a few seconds each. The built-in sounds are not files: each client makes them |
| Backups | server/default/backups/<backup or scheduled>-<time>.tar.age | Each one the whole instance (the database, the files, the certificate, the settings) sealed with age under a passphrase or the backup key; the server cannot open the ones sealed to the key. Written by tephro-server admin backup, the status view, the client's Admin → Backups or the backup_every schedule. Never sent anywhere by the server |
| What a restore replaced | server/default/.before-restore-<time>/ | The whole instance as it was before the last restore, kept so admin restore --undo can put it back; the next restore replaces it, and it is removed after rollback_copy_days (14). Until then it holds what was deleted after it, as the database copies do |
| VPN ranges | server/default/vpn-ranges.txt | Only if the operator ran tephro-server admin vpn-list update: the list used to flag (never block) sessions from VPN or hosting addresses |
| The log | server/default/tephro.log | When the server runs in the background or shows its status view, its log goes here instead of the terminal. It grows without a cap today; a size cap is planned |
| The status view's socket | server/default/admin.sock | How tephro-server tui and tephro-server admin shutdown reach the running server. Owner-only, created at start, removed at shutdown |
The systemd unit puts this directory at /var/lib/tephro/default (and another instance's at /var/lib/tephro/<name>); the container image at /data. --data-dir or TEPHRO_DATA_DIR moves it anywhere else.
What is never stored
- **Your private keys, anywhere but
client/default/secure.json** (and a profile's own.) Servers hold your public keys only. Nobody can log in as you from the server's disk. - Passwords in the clear. A server password, if you set one, is stored as an argon2id hash on the server; the client stores nothing of it.
- Calls. Voice, cameras and screen shares are end-to-end encrypted: the server forwards frames it cannot open and records nothing, and the keys of a call live in the memory of the clients in it until it ends.
- Channel messages on the client's disk. The app holds them in memory and fetches them from the server when it connects. Direct messages are the exception: the server forgets them once delivered, so each device keeps its own (above).
Deleting everything
Close the app, delete the client/ folder. If you also ran a server, stop it (tephro-server admin shutdown) and delete server/. Remove the program itself the way you installed it (the package manager, or the AppImage file). Your messages stay on the servers you posted them to, under your old name, so the conversations still make sense to the people who were in them; leave a server first if you want your account there to end.