Matrix Synapse Hidden Service: Federated Chat Over Tor
Matrix is an open standard for decentralized, federated communication that supports end-to-end encryption, persistent chat history, and rich media sharing. Synapse is the reference Matrix homeserver implementation used by millions of users across the federated Matrix network. Deploying Synapse as a Tor hidden service creates a Matrix homeserver that is reachable without exposing its IP address, allowing both server operators and users to maintain anonymity. The Matrix federation protocol is well-suited for .onion deployment - homeservers communicate with each other directly, and .onion homeservers can federate with both other .onion homeservers and clearnet homeservers through Tor egress. This makes Matrix-over-Tor an excellent choice for privacy-sensitive organizations that need persistent, searchable, multi-user communication with rich features including voice/video (WebRTC), bots, and integrations.
Need this done for your project?
We implement, you ship. Async, documented, done in days.
Synapse requires more resources than lighter alternatives like Conduit or Dendrite. Minimum for a private homeserver: 2GB RAM, 2 CPU cores, 20GB disk. Production deployments with federation and media storage: 4GB RAM, 4 cores, 100GB disk. Install via pip in a virtual environment or use the matrix-org/synapse Docker image. For production, the PostgreSQL backend is mandatory - SQLite is insufficient for federation. Create a PostgreSQL database and user: CREATE USER synapse_user WITH PASSWORD 'password'; CREATE DATABASE synapse OWNER synapse_user ENCODING 'UTF8';. Generate the initial configuration: python -m synapse.app.homeserver --server-name youronion.onion --config-path /etc/matrix-synapse/homeserver.yaml --generate-config --report-stats=no.
Tor Hidden Service Configuration for Matrix
Matrix uses port 8448 for server-to-server (federation) and port 8008 or 8448 for client-server API. Add to torrc: HiddenServiceDir /var/lib/tor/synapse/, HiddenServicePort 80 127.0.0.1:8008, HiddenServicePort 8448 127.0.0.1:8448. In homeserver.yaml, set server_name: youronion.onion. Configure public_baseurl: http://youronion.onion. For listeners, bind to 127.0.0.1 only to prevent clearnet exposure. The Synapse delegation mechanism (well-known or SRV DNS records) is not needed for .onion federation since port 8448 is standard. Ensure the homeserver.yaml TLS settings do not enforce certificate validation for .onion addresses when federating.
Federation with Clearnet and Other .onion Homeservers
Synapse can federate with clearnet Matrix homeservers through Tor egress. Configure Synapse to use Tor as a proxy for outbound federation requests by setting outgoing_requests_proxy: socks5://127.0.0.1:9050 in homeserver.yaml (where supported) or using torsocks wrapping at the process level. For federating with other .onion Matrix homeservers, both servers must be reachable at their respective .onion addresses. Add the remote server's .onion address to your federation allowlist if federation is restricted. Test federation with: curl http://youronion.onion:8448/_matrix/federation/v1/version. Federated rooms allow users from different homeservers to participate together, with message history replicated across all participating homeservers.
Element Web Client for .onion Homeservers
Element Web (formerly Riot.im) is the primary Matrix client available as a web application. Serve Element Web through the same .onion address under a different path or a subdomain of the .onion. Configure config.json for the Element deployment: set default_server_config with m.homeserver.base_url pointing to your .onion address. Users access the Element interface through Tor Browser, and the client connects to the .onion homeserver API. For mobile clients (Element iOS/Android), configure a custom homeserver URL pointing to the .onion address. Element Android handles .onion addresses when the Tor proxy is configured on the device. Cinny and FluffyChat are lightweight alternatives to Element that work well over Tor's latency characteristics.
Anonymous Room Creation and Access Control
Matrix rooms can be public (anyone with the room ID or alias can join), invite-only (users must be invited), or knock-enabled (users can request access). For anonymous Tor deployments, configure rooms as invite-only by default. Room aliases (@roomalias:youronion.onion) allow users to find rooms without knowing room IDs. Disable public room directory for private instances. Configure registration with registration_requires_token: true, requiring a token distributed through trusted channels. For guest access, enable allow_guest_access: true only in specific rooms designated for anonymous participation. Moderation tools including room admin commands, server-wide bans, and room state control are available to homeserver administrators through the Synapse admin API.