Tephro · Guides
Running a Tephro server
One binary, one directory, one port. This is the whole procedure; if a step here does not work, that is a bug worth reporting.
1. Get the binary
Download the build for your platform from the releases page (five targets: Linux amd64/arm64, Windows amd64, macOS amd64/arm64), or build it yourself with Go 1.27+:
git clone https://gitlab.com/encenillo/tephro cd tephro && make server-build # → dist/server/tephro-server
Check the download: every release ships SHA256SUMS and its OpenPGP signature SHA256SUMS.asc, made with the maintainer's signing key on a hardware token. With gpg installed:
curl -fsSL https://gitlab.com/AuHunt.gpg | gpg --import gpg --verify SHA256SUMS.asc SHA256SUMS sha256sum -c SHA256SUMS
The second line must report a good signature from a key with the primary fingerprint 3174 0E3B 30C6 597B 5578 FE09 A760 51A5 9D84 E725; the third proves the binary matches the checksums. Then give the file its command name, tephro-server: mv tephro-*-linux-amd64 tephro-server && chmod +x tephro-server (on Windows, rename the .exe to tephro-server.exe). On Arch, the AUR's tephro-server-bin does all of this: the release binary as /usr/bin/tephro-server, the systemd units, the tephro user and /var/lib/tephro, which holds the instance in default/; upgrade it with yay or paru, since tephro-server admin upgrade never swaps a file a package manager owns. The same key is embedded in the desktop client, which runs the same two checks before installing an update. Nothing else is needed on the box: no database server, no reverse proxy, no TURN daemon.
From our repository (Debian, Ubuntu, Fedora, openSUSE)
We recommend this on those systems and their relatives. Our repository installs the same release binary as a package, for x86-64 and 64-bit ARM, and it updates with the rest of the system. It is your choice: your system checks tephro.chat for new versions when it checks for updates, and installs them as root. These checks carry nothing from your server; the host sees your IP address, as with any download.
# Debian, Ubuntu, Raspberry Pi OS (64-bit) sudo curl -fsSL --create-dirs -o /etc/apt/keyrings/tephro.asc https://tephro.chat/repo/tephro.asc sudo curl -fsSL -o /etc/apt/sources.list.d/tephro.sources https://tephro.chat/repo/tephro.sources sudo apt update && sudo apt install tephro-server # Fedora, RHEL, Rocky, Alma sudo curl -fsSL -o /etc/yum.repos.d/tephro.repo https://tephro.chat/repo/tephro.repo sudo dnf install tephro-server # openSUSE sudo zypper addrepo https://tephro.chat/repo/tephro.repo sudo zypper install tephro-server
dnf and zypper ask whether to trust the key; its fingerprint is the one above. The package puts the binary at /usr/bin/tephro-server with the systemd units, the tephro user and /var/lib/tephro (the instance lives in its default folder), and leaves the service stopped. Start it, then mint the owner invite:
sudo systemctl enable --now tephro-server sudo -u tephro tephro-server admin invite --owner --data-dir /var/lib/tephro/default
Under systemd there is no wizard: the server boots on defaults, and the unit already grants port 443 (section 3). Change settings with sudo -u tephro tephro-server admin config set <key> <value> --data-dir /var/lib/tephro/default or in the status view (sudo -u tephro tephro-server tui --data-dir /var/lib/tephro/default), starting with public_ip behind a home router. Upgrades come with the system's (apt upgrade, dnf upgrade, zypper update), and a running server restarts onto the new binary; tephro-server admin upgrade leaves a package's binary to the package manager. The .deb and .rpm are also on the releases page, for a machine that should not add the repository; those do not update by themselves. The .deb asks at install whether to add it (an unattended install counts as no; to say yes, first run echo 'tephro-server tephro/add-repository boolean true' | sudo debconf-set-selections), and the .rpm prints how. The .rpm is signed with the release key, and Fedora refuses it until the key is imported, once: sudo rpm --import https://tephro.chat/repo/tephro.asc. apt purge of the last Tephro package removes a repository that question added. To remove it yourself, delete /etc/apt/sources.list.d/tephro.sources and /etc/apt/keyrings/tephro.asc, or /etc/yum.repos.d/tephro.repo, or run sudo zypper removerepo tephro-server and sudo zypper removerepo tephro-client.
On Gentoo, our overlay installs the same binary with an OpenRC script beside the systemd units, and creates the tephro user and /var/lib/tephro:
sudo eselect repository add tephro git https://gitlab.com/encenillo/tephro-overlay.git sudo emaint sync -r tephro sudo emerge -a net-im/tephro-server-bin sudo rc-service tephro-server start # systemd: sudo systemctl enable --now tephro-server sudo rc-update add tephro-server default
The listen address and extra flags are in /etc/conf.d/tephro-server; the owner invite and everything else are the same commands as above. Upgrades come with emerge -u.
On NixOS, our flake's module runs the same binary as a service, with the tephro user and /var/lib/tephro. In your system's flake:
inputs.tephro.url = "gitlab:encenillo/tephro-nix";
modules = [
inputs.tephro.nixosModules.default
{ services.tephro-server = { enable = true; openFirewall = true; }; }
];
nixos-rebuild switch starts it; settings stay in tephro.toml, and the owner invite and everything else are the same commands as above. Upgrades are nix flake update tephro and another rebuild. Going back to an earlier system generation changes the binary, not the data, so a database a newer server has migrated stays migrated: restore a backup for that.
In a Proxmox container
The server can run in an unprivileged Debian container, from our repository. On the Proxmox host, download the template and create the container. nesting=1 lets the service's sandboxing work, and the sizes are a starting point: uploads count toward the disk.
pveam update pveam available --section system | grep debian-13 pveam download local debian-13-standard_<version>_amd64.tar.zst pct create 120 local:vztmpl/debian-13-standard_<version>_amd64.tar.zst \ --hostname tephro --unprivileged 1 --features nesting=1 \ --cores 2 --memory 2048 --rootfs local-lvm:16 \ --net0 name=eth0,bridge=vmbr0,ip=dhcp --onboot 1 pct start 120 pct enter 120
Inside the container you are root and there is no sudo:
apt update && apt install -y curl ca-certificates curl -fsSL --create-dirs -o /etc/apt/keyrings/tephro.asc https://tephro.chat/repo/tephro.asc curl -fsSL -o /etc/apt/sources.list.d/tephro.sources https://tephro.chat/repo/tephro.sources apt update && apt install -y tephro-server systemctl enable --now tephro-server runuser -u tephro -- tephro-server admin invite --owner --data-dir /var/lib/tephro/default
The container has its own address, so give it a fixed one, and forward TCP 443 and UDP 443 from your router to it, not to the Proxmox host (section 3). If the Proxmox firewall is on, allow both there too. Then set public_ip:
runuser -u tephro -- tephro-server admin public-ip --data-dir /var/lib/tephro/default
Anywhere this guide says sudo -u tephro, use runuser -u tephro -- here. Upgrades come with apt upgrade inside the container, or on a schedule (systemctl enable --now tephro-server-update@default.timer, then auto_update; section 5, Updating by itself), and the data is in /var/lib/tephro, so a Proxmox backup of the container includes it.
2. Run it once
./tephro-server
In a terminal, the first run is a short setup wizard: instance name, listen address, TLS mode, admission mode, whether to mint the owner invite, your public IP (detected with one request to Mullvad's echo service, typed, or skipped), and which address the owner invite link should carry — the public one, this machine (127.0.0.1, when the client runs on the same box), or one you type. **On Linux, as an ordinary user, the very first thing you may see instead is permission denied on port 443** — that is section 3, one command, and the wizard walks you through it when there is a terminal. It writes tephro.toml into the data directory, prints the owner invite, and then the server goes to the background and your shell comes back with the process id and the log path. tephro-server tui shows the live status view whenever you want it; tephro-server admin shutdown stops the server. The data directory is the one place the server writes: by default ~/.local/share/tephro/server/default on Linux (%LOCALAPPDATA%\Tephro\server\default on Windows, ~/Library/Application Support/Tephro/server/default on macOS — the desktop client keeps its own files beside it under the same root), or wherever --data-dir / TEPHRO_DATA_DIR points; TEPHRO_HOME moves the whole root. default is the instance's name: a second one on the same machine is --instance NAME, in the folder of that name beside it (More than one instance on a machine, section 5). Run the binary from any directory and it finds the same instance. Every answer is also a config key, so a headless box (a container, a service manager) needs no wizard: it boots on defaults and logs what to change.
The one thing to know: the owner is whoever registers with the owner invite. Mint it in the wizard or later with
./tephro-server admin invite --owner
and register with that key from the desktop client. If the owner disappears — the person is unreachable, their machine is gone — mint a replacement from the box: tephro-server admin invite --owner --force. Whoever registers with it becomes the owner and the previous owner loses the flag (the audit log records it). Without --force the command refuses while an active owner with keys exists and points at tephro-server admin owner <username>, which moves ownership to an existing account instead. Every later invite comes from the client, or from tephro-server admin invite: a plain one is a personal key (one use, admits directly); --public makes a public link (unlimited uses) whose joiners wait for your approval unless you pass --approval no or turn the public_invite_approval setting off. tephro-server admin approvals lists who is waiting; approve <name> and deny <name> decide. Every invite is printed with a second, same machine link for a client running on this box.
Direct messages are not kept on the server: it holds each one only until the devices it is for have it (dm_relay_days, 30, at most). What one member's files may take while they wait is capped too, dm_queue_gb (1): past it their next file is refused until earlier ones are delivered, so a member cannot park a pile of files for someone who never comes online. It always fits one file of the largest size: with max_upload_mb above it, the queue counts as max_upload_mb. When a member adds a device, or lost every copy of a conversation, their history goes from device to device through the server's memory, never its disk: at most two 4 MiB chunks per sync, four syncs at once, all of them together held to dm_sync_cap_mbps (10). Each account may send dm_sync_daily_gb (5) a day; past that the member asks an admin. The request (who, which devices, how big) shows in the client's Admin → Members under the join requests, for anyone with Manage server, and on the status view's 5 screen (a approves, n denies); tephro-server admin dm-syncs lists it for admin dm-sync approve <id> or deny <id>.
3. Ports
The server listens on TCP 443 (HTTPS, the client's websocket, and the ICE-TCP fallback) and UDP 443 (all voice and video, every call, one port). Nothing else. Members' networks are least likely to block 443, which is why it is the default and why you should keep it if you can.
Linux needs one grant to bind a port below 1024. Pick whichever fits how you run it:
| How you run it | What to do |
|---|---|
| By hand | sudo setcap cap_net_bind_service=+ep ./tephro-server — repeat after replacing the binary |
| systemd | Use server/deploy/tephro-server.service; it carries AmbientCapabilities=CAP_NET_BIND_SERVICE |
| Container | Publish the port (-p 443:443 -p 443:443/udp). Rootful docker or podman: nothing else. Rootless podman refuses ports below 1024: sudo sysctl net.ipv4.ip_unprivileged_port_start=443 (and a file in /etc/sysctl.d/ to keep it), or publish a high host port (-p 8443:443 -p 8443:443/udp) and have the router forward external 443 to it — the server inside still binds 443, so this is the one place a port translation works |
| Behind a home router | Grant the bind as above and forward external 443 → 443, TCP and UDP, to this machine. Set public_ip — the wizard detects it, or run tephro-server admin public-ip. Details below |
The wizard test-binds your chosen port and walks through these on a permission error. Windows and macOS do not restrict low ports.
Behind a home router
The port must be the same on both sides of the router. The server advertises the port its socket is bound to, and the client aims at the port in the invite link, so a rule that translates external 443 to an internal 8443 leaves every call knocking on a port nobody forwarded. Two shapes work:
- 443 both sides (recommended): grant the bind (the table above),
listen = "0.0.0.0:443", router forwards TCP 443 and UDP 443 to this machine. Members reach the least-blocked port. - A high port both sides:
listen = "0.0.0.0:8443", router forwards TCP 8443 and UDP 8443. No grant; the invite link carries:8443; members on restrictive networks may not reach it.
Then public_ip, which is also the address an invite link names when it is made by someone connected over a local address; domain goes first when set. The wizard's detect asks an echo service once and writes the literal address; tephro-server admin public-ip does the same later. Without it the server's offers name only its LAN address and calls never find the way in. Home addresses change: when yours does, run it again and hand out fresh links, or point a DNS name here and set domain. Members on your own LAN get a link with the LAN address — tephro-server admin invite --host 192.168.1.10 — because most home routers do not route a LAN client out and back in.
Before inviting anyone, open https://<public_ip> from a phone on mobile data. The certificate warning is expected (self-signed); the page behind it is the instance's own. If nothing loads, check the forward rule and this machine's firewall, then whether your ISP puts you behind carrier-grade NAT: the router's WAN address is in 100.64.0.0/10 or differs from the detected public IP. Behind CGNAT no forward works and a VPS is the answer.
4. TLS and the fingerprint
By default the server generates a self-signed certificate on first run and prints its fingerprint. The desktop client pins that fingerprint — it does not need a certificate authority, so a bare IP address works. The fingerprint travels inside every invite link (tephro://join?host=…&fp=sha256:…&key=…), so a member's first connection is verified rather than trusted.
If you have a DNS name and port 443 reachable from the internet, tls_mode = "acme" with domain = "chat.example.org" gets a Let's Encrypt certificate automatically. If a reverse proxy terminates TLS in front, tls_mode = "off" and trusted_proxies set to the proxy's address, so rate limits and logs see your members rather than the proxy (never set it on a server members reach directly).
5. Keeping it running
- From a shell, it runs in the background.
tephro-serverstarts the server as a background process (its output goes totephro.login the data directory) and comes back once it is serving, with the process id and the log path; if it dies at once — the port is taken, or not yet granted — you see the log's end right there. Closing the terminal changes nothing. Stopping it:tephro-server admin shutdownfrom any shell, orQin the status view; both are the same clean stop as Ctrl-C.tephro --foregroundkeeps it in the terminal instead (Ctrl-C stops it);tephro-server --tuiserves and shows the status view in the same terminal. - The view is separate from the process. However it runs — in the background, under systemd, in a container, from a Windows shortcut —
tephro-server tuifrom any terminal attaches the live status view to it, andqthere only detaches. No tmux needed. Under systemd the socket belongs to thetephro-serveruser, sosudo -u tephro tephro-server tui --data-dir /var/lib/tephro/default. On Windows, runtephro-server.exefrom a shortcut, thentephro-server tuiin any PowerShell window. - Under systemd or in a container nothing changes: with no terminal the server stays in the foreground, which is what the service manager or the runtime expects. (It also recognises systemd and the common container runtimes when they do hand it a terminal.)
- systemd:
server/deploy/tephro-server.service— hardened, restarts on failure, data in/var/lib/tephro/default.server/deploy/tephro-server@.serviceruns more instances beside it (below). - Container:
podman run -d --name tephro -p 443:443 -p 443:443/udp -v tephro-data:/data registry.gitlab.com/encenillo/tephro/server(amd64 and arm64). The same image is on Docker Hub astephrochat/tephro-server. The image is the release binary and nothing else; the whole instance lives in the/datavolume. Admin commands run inside it:podman exec tephro /tephro-server admin invite --owner. Upgrade by replacing the container:podman pull,podman rm -f tephro, then the samepodman run. A restart keeps the old image; the volume keeps the instance. Each version is also a tag (…/server:0.7.0); the image holds the published release binary, checked against its signed checksums before it is packed. From 0.24.0 on, each image is signed with cosign, with no key to trust: the signature names this project's CI onmain. Check one withcosign verify registry.gitlab.com/encenillo/tephro/server:0.24.0 --certificate-identity 'https://gitlab.com/encenillo/tephro//.gitlab-ci.yml@refs/heads/main' --certificate-oidc-issuer https://gitlab.com, and the same fordocker.io/tephrochat/tephro-server. To build it yourself:make release-server, thenpodman build -f server/deploy/Containerfile .. - Backup:
tephro-server admin backupwrites the whole instance (database, files, certificate,tephro.toml) as one archive intobackups/in the data directory, sealed with age: a passphrase it asks for (enter alone generates one, shown once) or, with--key, your backup key. It works while the server runs. Copy it off the machine yourself: a backup on the same disk is lost with it, and the server never sends one anywhere. For a schedule, make a key withtephro-server admin backup-key(the public half becomesbackup_key, the private half is printed once: keep it in a password manager or on paper, never on this machine), then setbackup_every(daily, orweeklyonbackup_day,sundayunless you pick another),backup_at(04:00) andbackups_keep(3 scheduled ones kept; backups taken by hand stay until you remove them). Use one passphrase or key per server instance and per client profile, used for nothing else, so one leak opens one.tephro-server admin backupslists them; the status view's7screen and the client's Admin → Backups show them too, and the client can start one (owner, or Operate server). Opening one without Tephro:age -d -i key.txt backup-….tar.age | tar -x. Stopping the server and copying the data directory is still a full copy too, unsealed. - Restore, or moving to another machine:
tephro-server admin restore <backup>(a name inbackups/or a path,--identity key.txtfor a key) unpacks it beside the data, then swaps it in; the instance it replaces is set aside whole, andadmin restore --undoputs that back, forrollback_copy_days(14). A running server restarts into it. A restore rewinds the whole community to the backup's time. The backup carries the certificate and its key (a sealed key too, when the running server writes the backup), so on a new machine members' clients still trust it; stop the old server first, since two copies would share every key and session. A release older than the backup refuses it. From the desktop app, Admin → Backups restores a backup already inbackups/, an upgrade snapshot, or undoes the last restore (owner, or Operate server, with 2FA where it is asked). The passphrase, or the backup key's private half for a scheduled backup, goes to the server over the app's TLS connection and is used once, never stored. Every member is told, and the server restarts into it. Nothing is uploaded: a backup from elsewhere goes intobackups/by your own means first. - Upgrade:
sudo tephro-server admin upgradefetches the newest release for your OS and architecture, verifies the maintainer's signature and the checksum before anything touches disk, then asks before it swaps the binary and restarts the server — every call drops for a few seconds. Under systemd the service keeps its PID and its journal; run it with sudo because/usr/local/binand the unit'sProtectSystem=strictkeep the service itself from writing there. A background server started withtephro-serverkeeps itstephro.log. In a container, pull the new image and recreate the container instead; the command says so. If you set the port capability withsetcap, the upgrade re-applies it when run as root, or prints the line. A release that asks you to know something before or after it says so in its notes under Heads up; the server prints those lines at every start and counts them as warnings on the status view's overview (wlists or hides them), andtephro-server admin headsuplists every release's.ron the overview andtephro-server admin notes [version]show a release's notes.--checkshows what would happen;tephro-server admin restartrestarts without upgrading; the status view'sUkey is the same flow: it asks y/n before downloading anything, then confirms again before the swap. By hand it is still just: replace the binary and restart (re-runsetcapon Linux if you used it). An instance from before 2026-09-18 has no AFK channel — the bootstrap only creates channels on an empty instance — so add one once:tephro-server admin channel add AFK --afk, or tick AFK channel on a voice channel in the client's Admin → Channels. The server checks for a newer release only if you ask it to:update_check_everyisoffby default, orstart,1h,6h,24h(tephro-server admin config set update_check_every 24h, the status view's settings, or the client's Admin → Server). A newer release is logged, shown as a tag at the top of the status view, and shown to members with Manage server in the client's Admin dialog. It updates itself only if you turn that on (next item); otherwise you run the upgrade, or the owner (or a member they gave Operate server) presses Update server in the Admin dialog, which runs the same download, signature check, swap and restart. That button is refused in a container, on a package's binary, where the server's own user cannot write the folder its binary is in, and where the binary carries the port 443 capability and the server does not run as root (a new file would lose it); the dialog then showssudo tephro-server admin upgrade. Every call drops while the server restarts. - Updating by itself:
auto_updateisoffby default, ordailyorweekly(tephro-server admin config set auto_update weekly,Aon the status view's overview, its settings, or Admin → Server in the client). Once it is on, the overview shows it under the release, with the next run. It runs atauto_update_at,04:00unless you change it, and a weekly one onauto_update_day,mondayunless you change it, both in the server's own time zone. Ten minutes before, the server looks for a newer release; if there is one, everyone connected is told it restarts for an update, and at the time it downloads it, checks the signature and the checksum, swaps the binary and restarts, likeadmin upgrade. If anyone is in a call it waits for the calls to end, two hours at most, and then gives ten minutes' notice. A release with a Heads up in its notes is never installed this way: it waits for you to read them. The upgrade's database snapshots andtephro.oldare the way back (next item). A server that was down at the time skips that day's update. The Admin dialog's Server section says when the next one runs and what is in its way. - With the systemd unit (/usr/local/bin, the service running astephro) the server cannot replace its own binary, so a root timer does the swap. Install it beside the unit and start it for the instance,defaultfor the onetephro-server.serviceruns:sudo install -m 0644 server/deploy/tephro-server-update@.service server/deploy/tephro-server-update@.timer /etc/systemd/system/, thensudo systemctl enable --now tephro-server-update@default.timer. Every five minutes it asks the running server whether an update is due and does nothing otherwise, so the restart comes within five minutes of the time. It needs the admin socket (admin_socket, on by default).journalctl -u tephro-server-update@defaultshows what it did. Until it has asked once, the Admin dialog says it is missing. - A server you run yourself from a folder its user can write (a home directory, a detachedtephro-server) swaps its own binary and needs no timer. - From our apt or rpm repository (Debian, Ubuntu, Fedora, openSUSE, the Proxmox container below) the package ships the same timer, already pointing at/usr/bin. Start it withsudo systemctl enable --now tephro-server-update@default.timerand the schedule does the rest: at the time,apt-get,dnforzypperupgradestephro-serverand the server comes back on the new release. Nothing starts it for you: the package prints that line when it is first installed, and whileauto_updateis on and the timer is off, the Admin dialog, the status view andadmin config setshow it. If the repository does not carry the release yet (it is updated just after each release), nothing changes and the next scheduled update takes it. The system's own unattended updates (unattended-upgrades,dnf-automatic) also work, without the call hold and the notice. - Everywhere else the server says how it updates, in the Admin dialog, the status view and the log, instead of updating: a.debor.rpmdownloaded without our repository (add the repository, or install each release's package), the AUR (yay -Syu tephro-server-binorparu -Syu tephro-server-bin, by hand), Gentoo (emerge), Nix (a rebuild, or NixOS'ssystem.autoUpgrade), a container (pull the new image and recreate it;podman auto-updatewith the labelio.containers.autoupdate=registrydoes it on a schedule). - Going back after an upgrade: a start that changes the database's layout first copies it beside itself as
tephro.db.pre-<number>, and does not start at all if that copy cannot be written, a full disk say; once the changes are done it copies the result astephro.db.post-<number>. One of each is kept, from the latest upgrade, forrollback_copy_days(14;0keeps them), since a bad upgrade shows within days. They hold the database only, not the files. If a release misbehaves, stop the server, runtephro-server admin restore-snapshot(it lists both, puts backbeforeby default and keeps the database it replaced astephro.db.replaced), and start the previous binary:tephro.oldbeside it after an upgrade the server did itself, kept for the samerollback_copy_days, or the package manager's older version. Whatever members posted since the upgrade is lost. An older binary never runs on a database a newer one changed: it stops, names both releases and points at the copy.
Encrypting the disk
Who it is for: mostly a rented machine, whose disks, snapshots and backups are out of your hands. On a box you own and keep at home it is rarely needed. Direct messages and calls are already end-to-end encrypted, so their content is never on the disk in the clear; channel messages, files, the member list and the certificate's key are.
Tephro does not encrypt its folder itself. Your system does it better, and for everything at once:
- Linux: LUKS on the disk or on a volume for the data (most installers offer it; on a rented server, a second volume encrypted with
cryptsetupand unlocked after boot). To encrypt only the data directory: fscrypt (ext4, F2FS) or gocryptfs. - Windows: BitLocker, or Device encryption on Home.
- macOS: FileVault.
- A cloud volume: most providers have an encryption switch on the volume. It guards their disks, not your running machine.
At every start the server says what it found: Disk encryption: detected (LUKS), no encrypted volume detected (ZFS and btrfs native encryption, self-encrypting drives and VeraCrypt do not show, so this does not always mean unencrypted), or unknown. The same line is in the status view, tephro-server admin security and the client's Admin → Server. It also warns when the data directory is open to other users (chmod 700 on it closes it).
The certificate's key can be sealed (Linux with systemd): sudo tephro-server admin tls seal --data-dir /var/lib/tephro/default encrypts tls/key.pem with systemd-creds (bound to the machine's TPM2 when it has one), adds a drop-in that hands it to the unit at start, and removes the plain file. A copied disk or snapshot then holds no usable key, so nobody can pose as your server with it. Restart the server afterwards. admin tls unseal puts it back. Backups the running server writes still carry the key, inside the backup's own encryption; one written by tephro-server admin backup while the key is sealed does not, and says so. Snapshots and backups from before you sealed it still hold the plain key. A restore puts the backup's key back as a plain file, and the server uses it when the sealed one belongs to another certificate: tephro-server admin security then says to seal again (admin tls seal --yes).
An encrypted folder that is not unlocked yet looks empty. Started then, the server would take it for a first run and set up a new, empty instance. --require-mount=<path> (or TEPHRO_REQUIRE_MOUNT) stops that: the server, and every tephro-server admin command, exits before writing anything unless that path is mounted. Bare --require-mount means the data directory itself. Under systemd, a drop-in:
sudo systemctl edit tephro-server@default # add: [Service] Environment=TEPHRO_REQUIRE_MOUNT=/var/lib/tephro
What encryption leaves open: a running server holds its keys in memory, and whoever runs the machine underneath (a hosting provider, a hypervisor) can read that memory. It protects copies: a snapshot, a backup the provider keeps, a retired disk.
Guarding the machine's login
The status view and tephro-server admin ask for no password and no 2FA: whoever can run them as root or as the server's user can already read its database and key, so a prompt there would protect nothing. What protects them is the machine's own login. On a server you reach over SSH, start with keys only, no passwords, a drop-in /etc/ssh/sshd_config.d/50-keys-only.conf:
PasswordAuthentication no KbdInteractiveAuthentication no PermitRootLogin prohibit-password
Then sudo sshd -t (it must print nothing) and sudo systemctl reload ssh (sshd on Fedora, openSUSE and Arch). Keep your current session open until a new one logs in.
- A second factor: a hardware key holds the SSH key itself (
ssh-keygen -t ed25519-sk, OpenSSH 8.2 or later, any FIDO2 key such as a YubiKey), so a copied key file is useless without the device and a touch. Without one, a code from an authenticator app works through PAM (libpam-google-authenticatorwithAuthenticationMethods publickey,keyboard-interactive), at the cost of more setup. - Guessing: OpenSSH 9.8 and later slow down addresses that keep failing by itself (
PerSourcePenalties); on an older one, fail2ban does it.
Disk encryption (above) is the other half: it guards copies of the disk, this guards the running machine.
More than one instance on a machine
Each instance is one folder, named and beside the others: default is the one you get without a name, and every other instance has its own folder next to it.
| How you run it | The first instance | Another one, named two |
|---|---|---|
| By hand | ~/.local/share/tephro/server/default | tephro-server --instance two, in …/server/two; every admin and tui command takes --instance two too |
| systemd | tephro-server, in /var/lib/tephro/default | tephro-server@two, in /var/lib/tephro/two (server/deploy/tephro-server@.service, shipped by the packages) |
| OpenRC | tephro-server, in /var/lib/tephro/default | a link /etc/init.d/tephro-server.two → tephro-server, in /var/lib/tephro/two, settings in /etc/conf.d/tephro-server.two |
| Containers | one container per instance, each with its own /data volume |
Every instance takes TCP and UDP 443, so each needs its own address. The clean way is a second public IP on the machine, one per instance: set listen (and nothing else: media_udp follows it) to that address before the instance's first start. Under systemd:
sudo -u tephro tephro-server admin config set listen 203.0.113.7:443 --data-dir /var/lib/tephro/two sudo systemctl enable --now tephro-server@two sudo -u tephro tephro-server admin invite --owner --data-dir /var/lib/tephro/two
The first instance's listen moves to its own address the same way (the shipped unit sets 0.0.0.0:443, every address, through TEPHRO_LISTEN: override it with systemctl edit tephro-server or, under OpenRC, in /etc/conf.d/tephro-server, which a tephro-server.NAME reads too). A container gets its own address from the runtime. A second instance on another port (:8443) works, since members add a server as host:port, but it loses what 443 buys: the networks that let only 443 through.
A unit or an --data-dir that names a folder explicitly keeps using it.
6. Day to day
| Task | Where |
|---|---|
| Invite people, approve join requests, roles, channels, moderation, audit log | The desktop client, as an administrator. From the box: tephro-server admin audit prints the audit log, admin approvals [--history] what waits and what was decided |
| Mint an invite from the box, list or revoke invites, add, change, reorder or remove a channel, move someone in voice, transfer ownership, issue a recovery code, change the instance name or admission mode, see status, look up your public IP, stop the server | tephro-server admin … (run tephro-server admin help). tephro-server admin invite --note "for Sam" mints a personal key (--public a link, --local also prints the loopback link for a client on this box); tephro-server admin invites lists the keys that can still admit someone (--all for spent and revoked ones); tephro-server admin revoke <key> ends one; tephro-server admin shutdown stops the server |
| Roles and who may enter a channel | Each member holds one role: Owner, Moderator, Member and Guest to start, where Guest, what a newcomer gets unless their invite names another role, reaches only the general chat, the guest voice channel and AFK. tephro-server admin roles shows the tree; roles add <parent> <name> --without P,P makes a role below another, roles edit <role> --with P --without P changes one (a loss that roles below hold needs --cascade or --branch-off), roles rm <role>; admin member <username> --role R gives a role; admin invite --role Member mints an invite that skips Guest; admin channel edit and admin group edit take --open-to R (that role and every role above it may enter), --restrict R:P,P --open-tag T (that tag's holders may enter, guests too) and, for a channel, --guest (the general chat or the guest voice channel). Permission tags add to a member's role: admin tags add NAME --with P,P, tags edit, tags rm; admin member <username> --tag T gives one and --untag T takes it; a tag their role already covers is refused, and taken off when a new role covers it. The client's Admin → Roles edits the same tree and tags; Admin → Members gives roles and tags; Admin → Channels edits who may enter, the restrictions and the guest channels |
| The shared label list | tephro-server admin labels lists it; labels add NAME, labels rename OLD NEW (--merge folds two entries into one), labels delete NAME; the status view's members screen (2, its labels pane: g, or → twice from the members) does the same. max_labels (200) caps it |
| Park idle voice members | afk_timeout_minutes (30) is how long a member sits in voice without speaking, changing channel, muting, typing, sending a message or starting a stream before the server moves them to the AFK channel and shows them away. A member sharing a screen or a camera is never moved, and gets the full time again when the share ends; 0 turns it off. Needs an AFK channel (tephro-server admin channel add AFK --afk) |
| Ask for 2FA before changes | Off by default. Admin → Server in the desktop client (Action 2FA), or tephro-server admin config set require_factor on. Then the role editor has an Elevation column beside the permissions: a ticked permission asks everyone on the server for their 2FA, everything they set (a password and an app means both), before a change under it (reading never asks), and not again on that device for elevation_minutes (10). By default Operate server and Manage server are ticked, the two that touch your machine: updates, backups, storage, every setting (renaming the server too); from the box, factor_permissions (OperateServer,ManageServer, plus any of ManageRoles, ManageChannels, ManageInvites, ManageEmoji, ManageMessages, ModerateMembers, ModerateVoice, MoveMembers). Someone without 2FA is refused those changes until they add one under Settings → Account. Changing any of the three settings from a client always asks. The status view and tephro-server admin never ask: whoever runs them can read the data directory already. tephro-server admin security warns while it is off, and names the admins without 2FA |
| Help | tephro-server -h lists the commands; tephro-server admin -h the subcommands; tephro-server admin <cmd> -h one subcommand's flags. A command or flag that is renamed in a later release keeps working under its old name, with a warning naming the new one, so scripts do not break on an upgrade |
| Flag members on VPN or hosting addresses | tephro-server admin vpn-list update fetches the range list (one request, only when you run it; vpn_list_url in the config), then tephro-server admin vpn-list and the members screen mark them vpn. A flag for you to weigh, never a block. ip_ban_hours makes a ban also refuse the person's last addresses for a while; it is 0 unless you set it |
| Disconnect, time out, ban or unban someone without a client | tephro-server admin disconnect|timeout|ban|unban <username> [--reason S] (timeout takes --for 2h or --until <RFC 3339>; without either it clears the timeout), then kill -HUP <pid> (or systemctl reload tephro-server) so the running server ends their connection; or select them on the status view's members screen (2) and press x, t, b or u — that one applies at once. Disconnect lets them straight back in; timeout refuses their login until the time; ban keeps them out |
Live view of connections, members, voice, storage, recent log; invites (tephro-server admin storage prints the storage report, storage files, cull and rm free space) | tephro-server tui against the running server, or tephro-server --tui to serve and watch in one terminal. Every screen is boxed panes after btop, each naming its keys in its bottom edge; ←/→ move between a screen's panes, / filters the lit pane's list and o changes its sort. 1 overview — the server with your version, a newer one, and the warnings (the release's heads-up lines and any planned cull, shown as a count until w lists them; P postpones a cull, C runs it; r shows the release notes) beside graphs (upload against video_cap_mbit, download, connections, voice, streams; +/- change the span from 30 seconds to 24 hours, an hour by default) and of the storage (growth a day and when the cap fills), with the certificate's expiry and what waits for approval among the facts, and a small security pane under them (TLS, the certificate, the owner, admins without a second factor, open admission; tephro-server admin security prints the same with the fix for each and fails while one is a problem, for a timer or a monitor); 2 members, each with their role and tags, beside the label catalogue (r changes a role, T the tags, disconnect, timeout, ban, unban and m move to another voice channel on the members; new, rename, delete on the labels); 3 channels — the groups, the channels and who may enter the one picked (n new, e edit, d delete, J/K reorder; r renames a group, G moves a channel to another group; a edits who may enter: open to, the tags that let people in, a role's restrictions, the general chat and guest voice marks); 4 permissions — the role tree with each role's members and what sets it apart, beside the tags (n adds a role below the selected one or a tag, e edits, d deletes; every change shows what it does first, and a loss that roles below hold asks cascade down or branch off); 5 admission — what waits on an admin (join requests and DM history syncs past their daily budget, a approves, n denies; h shows who decided what and when, and the week's finished syncs) over the invites (n mints a key through a short form: who it is for, personal or public, approval, lifetime; r revokes, y copies the selected link); 6 storage — the usage by kind, the categories (enter narrows the files to one), the files (space marks, x removes, f frees space by a size or a percent after a preview, h shows what culls hold, where r restores and x purges) and the policies; 7 backups — the backups beside the snapshots of the latest upgrade and the schedule (n writes one, r restores the selected backup or snapshot after a review, u undoes the last restore, k makes a backup key); 8 logs — the server log, which rotates at log_max_mb, beside the audit log of every decision, which the database keeps, each with its own scroll and / filter (l opens it from anywhere, L opens tephro.log in your pager). s the settings screen, q detaches (the server keeps running), Q stops the server after a confirm. Do not share your screen while an invite is on it |
| Change a setting | Admin → Server in the desktop client (every key, applied at once where that is safe, the rest marked restart), or press s in the status view (every setting, one line of explanation each, saved to tephro.toml and applied at once where that is safe — the notice says which keys need a restart), or tephro-server admin config set <key> <value> from a shell (a running server applies it at once and says which keys wait for a restart; run it as the server's user, or it falls back to asking for kill -HUP <pid> / systemctl reload tephro-server), or edit tephro.toml (every key is commented), or the matching --flag / TEPHRO_* variable and restart. tephro-server admin config lists them all with their current values. A setting an upgrade renamed or retired is fixed in tephro.toml at the next start, its line kept; the old name still works meanwhile, with a warning in the log |
Storage limits (max_upload_mb for one file, storage_cap_gb for everything the server keeps, unlimited until you set it; there is no limit per member), custom-emoji switches (custom_emoji, stickers, gifs: on by default; members post them from their own collection, and the sizes are fixed), the disappearing-messages switch (expiring_messages, on by default), the pin limit (max_pins), the video cap (video_cap_mbit: the most video the server sends out in total, which is what protects your upload; it is unlimited until you set it, and both the status view's settings and the client's Admin dialog ask for your connection's upload speed and suggest three quarters of it, which you can change) and the per-member send ceilings (max_camera_kbit, max_screen_kbit: the most one camera or screen share may send, which clients honor) are yours to set; the defaults are generous and the server refuses honestly when a cap is hit rather than degrading everyone. disabled_codecs = "av1" takes a codec away from your members (vp8, vp9, av1, h264); by default all four are allowed and each client picks the one that suits its machine, so a member's stream is limited by nothing you did not turn on. Link previews are on by default: the server fetches a title and picture for links members post, so the link's host sees your server's address and never a member's. It fetches over https only: a site that answers only plain http gets no preview. link_preview_hosts = "youtube.com, *.wikipedia.org" limits it to sites you name, and link_previews = false turns it off if you would rather it made no outbound requests at all. The pictures and videos it keeps for previews are limited to 10 MiB and 50 MiB each (max_preview_image_kb, max_preview_video_mb); anything larger is left out of the preview. Lower them on a small disk, or set one to 0 for no limit; previews count against storage_cap_gb like everything else. tephro-server admin storage shows what the server holds by kind (attachments, link previews, custom emoji, avatars, the icon and banner, direct-message files in transit, the database), the free disk and the log; the status view's storage screen and the client's Admin → Storage show the same. Past the cap, uploads are refused and messages still go through. To free space, tephro-server admin storage files lists what can go, oldest first, with filters (--kind image,video,audio,other,preview,relay, --older-than 90d, --since, --before, --uploader, --channel, --larger-than 10MB, --uploader-left, --include-pinned, --order newest|largest), and admin storage cull with the same filters and --free 5GB or --percent 20 shows how many files and how much would go, then asks. A message keeps its text and says its file was removed; a link preview is no longer shown. Pinned messages' files stay unless you include them, avatars and the icon are never culled, and custom emoji go only by hand (admin storage rm <id>). What a cull takes is held under held/ for cull_hold_days (7) before it is deleted: admin storage held lists it, admin storage restore <id> brings it back, admin storage purge deletes it now. Held files are outside the cap but still on the disk, so they go early when the disk is nearly full, and storage cull --now holds nothing when you need the disk space today. Each run is a row in the audit log (admin storage audit). It goes through the running server when there is one. In the client, Admin → Storage does all of this for anyone with Manage server: the files with a thumbnail for pictures, videos and link previews, the same filters, marks to remove several at once, Free space… with its preview, and what culls hold, to restore or delete for good. A picture from a channel the admin cannot open shows as an icon instead of a thumbnail.
The server can also cull by itself, and never without warning. The easy way to set it up is the wizard: Admin → Storage → Set up automatic culling in the client, or a on the status view's storage screen. It asks for the cap and how old files may get, then shows what your answers would remove right now before anything is saved. tephro-server admin storage policies --with storage_cap_gb=50,cull_attachments_days=180 shows the same from the command line. The policies are settings: cull_fullness (on: past 90 % of storage_cap_gb, attachments and link previews oldest first down to 80 %; it needs a cap, and leaves DM files in transit to dm_relay_days), cull_previews_days (30: link previews older than that, the cheapest thing to lose since they are copies of other sites), cull_attachments_days, cull_previews_gb and cull_attachments_gb (off), cull_gifs_days (90: GIFs nobody has posted for that long; every post starts the count again), cull_emoji_days and cull_stickers_days (off: custom emoji and stickers stay until you remove them, and fullness leaves them alone), and cull_keep_pinned (on). When one would take something, the server announces it cull_notice_hours (24) ahead: a toast in the client for everyone with Manage server, a line on Admin → Storage with Run now and Postpone a day, a warning on the status view's overview (P postpones it, C runs it), and tephro-server admin storage policies, which also says what each policy would take right now (admin storage postpone|run <policy>). At its time it takes what matches then, and holds it like any cull. Changing one of these settings is looked at at once, so its notice shows straight away. A nearly-full stop mark the server could never reach is refused when you save it, wherever you save it: if pinned files, the database and the rest no cull takes already fill more than 80 % of the cap, the refusal says how much and which mark or cap would do. If it becomes unreachable later (pins grow), the policy warns instead and takes what it may. Direct messages between members are on by default and end-to-end encrypted, so your server holds only ciphertext; dms = false turns the relay off.
Something is wrong
permission deniedon startup: section 3.- Members cannot connect on a bare IP: check the fingerprint they see matches
tephro-server admin fingerprint; send them a full invite link so it is verified for them. - Voice connects but nobody hears anything: UDP 443 is not reaching the server. Behind a router, forward UDP as well as TCP, the same port on both sides, and set
public_ip(tephro-server admin public-ipprints it; the server never looks it up on its own). On a VPS, open UDP 443 in the provider's firewall. Members on networks that block UDP entirely fall back to ICE-TCP on 443 automatically. - Logs: stdout when service-managed (JSON),
tephro.login the data directory when the terminal shows the status view or the server runs in the background.Lin the status view opens that file in your pager. While anyone is in voice the log carries amedia …line per stream every five seconds: attach it to a quality report.enhanced_logging = falseleaves those lines out, and the log then holds weeks rather than evenings. Pastlog_max_mb(100) the file starts again and the one before is kept astephro.log.1, so the log takes at most 200 MB. A busy evening (ten in voice, two streams watched) writes about 9 MB an hour, so that is several evenings back. Setlog_max_mb = 0to let it grow; the journal and a container engine size stdout themselves.