Tephro · Guides
Your data
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.
client/ — the desktop app
| What | Where | What is in it |
|---|---|---|
| Your keys | client/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, 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, 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) the OS falls back to obfuscation rather than encryption — the passphrase is worth setting there |
| Server certificates you trust | client/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/desktop.json | What closing the window does (quit, tray, ask) and the few other preferences of the window itself |
| Pictures the home screen needs offline | client/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/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/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/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). Capped at 10 MB with two previous files kept, about 30 MB at most. Never holds your keys, tokens, invite keys, passwords or message text. Settings → Storage → Log file opens the folder. Every kind of line is listed in DEBUGLOG.md |
| How the last run ended | client/logs/run.json | 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 |
| Crash dumps | client/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/profiles/<name>/ | Everything above, once more, when you start the app with --profile <name> |
| The browser engine's own files | client/Cache/, client/GPUCache/, client/Local Storage/, client/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 backup (Settings → Backup), 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. 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.
| What | Where | What is in it |
|---|---|---|
| Settings | server/tephro.toml | Every setting, commented. The status view's settings screen and tephro admin config set write this same file |
| The database | server/tephro.db (plus -wal and -shm while running) | Accounts (public keys only — the server never sees a private key), roles, channels, messages, read state, invites, the audit log. Direct messages are stored sealed: the server relays ciphertext it cannot read |
| The certificate | server/tls/cert.pem and server/tls/key.pem | Generated once on the first run (ten years, self-signed); server/tls/acme/ when Let's Encrypt is used instead. The key file is readable by the server's user only |
| Uploads | server/attachments/<id> | Every file members posted in channels |
| Sealed DM files | server/dmfiles/<id> | Files sent in direct messages, encrypted by the sender; the server cannot open them, and they go when their sender leaves |
| Pictures | server/avatars/<user id>, server/avatars/instance and instance-banner, server/emoji/<id>, server/embeds/<id> | Members' avatars, the instance icon and banner, custom emoji, and the pictures and short videos of link previews the server fetched |
| VPN ranges | server/vpn-ranges.txt | Only if the operator ran tephro admin vpn-list update: the list used to flag (never block) sessions from VPN or hosting addresses |
| The log | server/tephro.log | When the server runs in the background or shows its status view, its log goes here instead of the terminal |
| The status view's socket | server/admin.sock | How tephro tui and tephro admin shutdown reach the running server. Owner-only, created at start, removed at shutdown |
The systemd unit puts this directory at /var/lib/tephro; 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/secure.json.** 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.
- Channel messages on the client's disk. The app holds them in memory and fetches them from the server when it connects; closing a direct message on one device drops nothing, the history is fetched again the next time you open it.
- Anything about you on any central service. There is none — no directory, no account server, no telemetry. The only network requests outside your own servers are the ones you trigger: the update check at start (a public releases page, if you leave it on), the detect my public IP button an operator may press once, link previews, which the server fetches in channels and the sender fetches in DMs, and a platform's player, which your client loads from that platform when you click play on a card.
Deleting everything
Close the app, delete the client/ folder. If you also ran a server, stop it (tephro 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.