Matrix/Element Chat Server on Tor Hidden Service

Install Synapse via the official Debian/Ubuntu repository or pip. Synapse requires Python 3.8+, PostgreSQL (recommended over SQLite for production), and 1-2 GB RAM at minimum. During configuration in homeserver.yaml: set server_name to your .onion address (e.g., youronion.onion), set bind_addresses to ['127.0.0.1'] to prevent clearnet exposure, and configure the database connection to the local PostgreSQL instance. The Tor hidden service maps port 8448 (Matrix federation port) and port 443 (client port) to their respective localhost addresses. For a private, non-federated homeserver (no Matrix federation with external servers): set federation_domain_whitelist: [] in homeserver.yaml to disable federation entirely. This keeps all communication within your server without federation to matrix.org or other homeservers.

Element Web (the browser client) can be self-hosted as a static site served from the same .onion server. Build Element Web from source or download a release and serve via nginx. Configure Element Web's config.json to point to the local Synapse homeserver: set default_hs_url to http://youronion.onion:8448 and disable the public Matrix server discovery. Users access Element Web via the .onion address in Tor Browser. Element Desktop application can be configured to use a custom homeserver - users enter the .onion homeserver address in the homeserver configuration field. Both work over Tor when the client machine runs Tor and routes connections through SOCKS5. End-to-end encryption (E2EE) in Matrix uses the Megolm protocol - messages are encrypted by the client before sending, and the server stores only encrypted ciphertext. Even a compromised Synapse server cannot read messages without the clients' private keys.

Matrix on .onion can be configured for anonymous registration. In homeserver.yaml: set enable_registration: true and enable_registration_without_verification: true to allow registration without email or phone verification. This allows users to create accounts with only a username and password. For controlled access: set enable_registration: false and use registration_shared_secret to generate invitation tokens manually (synapse_register_user command). Distribute tokens via a secure channel. User display names in Matrix are chosen by users - no real-name requirement. The Matrix user ID format is @username:youronion.onion. This full user ID is the identity within Matrix, and users can share it out-of-band for others to add them as contacts.

Matrix bridges connect Matrix rooms to other messaging networks. Most bridges (Telegram, Signal, WhatsApp) connect to clearnet APIs, which would expose the server IP (or Tor exit IP) to those services. For .onion Matrix servers: use only bridges to other .onion or Tor-accessible services, or accept that bridges to clearnet services will reveal Tor exit node IP (not the server's real IP). Useful integrations that work within Tor: bridge to another Matrix homeserver via federation over Tor (configure the federation connection to use Tor SOCKS5), and Synapse's built-in webhooks for bots that connect to local services. For a fully isolated .onion Matrix server: disable all bridges and federation - the server is a closed community.

Back up Synapse data: PostgreSQL database (pg_dump) contains all messages, room state, and user data. The media store directory contains uploaded files and avatars. Encrypt both before backup. Matrix's Security Key (used for cross-device key verification and message key backup) is generated by clients - instruct users to export and securely store their Security Key for account recovery. Server-side key backup (Synapse's key backup feature) stores encrypted copies of message keys in the database, decryptable only by clients with the Security Key. This allows session recovery without losing message history. Room keys are stored per-room and per-user - long-term sessions accumulate many room keys. Advise users to periodically verify devices and remove obsolete sessions from their account settings.