# Synapse: the reference Matrix homeserver you run yourself

> Synapse is Element's Python and Rust Matrix homeserver, dual-licensed AGPL or commercial. It is the software you deploy when you want to own a federated chat server rather than rent one.

**element-hq/synapse** — Synapse: Matrix homeserver written in Python/Twisted + Rust

- Repository: https://github.com/element-hq/synapse
- Website: https://element-hq.github.io/synapse
- Stars: 4,665 · Forks: 622
- Language: Python
- License: AGPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/element-hq-synapse

## What Synapse actually is, and who ends up running it

Synapse is a homeserver: the server side of Matrix, the open standard for interoperable real-time communication. A homeserver stores user accounts, rooms and message history for its own users, and speaks the Matrix federation protocol to other homeservers so that a user on your server can talk to a user on someone else's. Element writes and maintains it, and the repository is the reference implementation of the protocol rather than one vendor's private fork.

The audience is narrower than the download numbers suggest. If you are an individual who wants a chat account, you join an existing homeserver and never touch this code. Synapse is for administrators: an organisation that needs its own domain, its own retention rules and its own data location; a community that wants federation with the wider Matrix network; a developer building on Matrix who needs a server to test against. The README is explicit that there is no support from Element unless you hold a subscription, and that the officially supported deployment path is the Element Server Suite, not a bare install from this repository.

## The Python and Rust split, and what it means for your server

The bulk of Synapse is Python on Twisted, with a Rust component compiled from the rust/ directory. The Cargo.toml at the repository root declares the whole tree a workspace with rust as its single member, so cargo commands run from the root. The pyproject.toml describes the package as matrix-synapse, requires Python 3.10 or newer and below 4.0, and classifies it as Production/Stable under the topic Communications :: Chat.

The dependency list is where the design shows. canonicaljson is pinned below 3.0.0, signedjson below 2.0.0, and unpaddedbase64 is required at 2.1.0 or higher. Those are the primitives of Matrix event signing and hashing: canonical JSON so two servers hash the same event identically, signed JSON so federation can verify who sent what, and unpadded base64 because the protocol specifies it. The version bounds are not incidental. A breaking change in event serialisation would break federation with servers running other versions, so the pins are part of the protocol surface.

Two consequences follow for operators. First, you are running a Python service with a compiled extension, so your deployment has both a Python runtime and a Rust build step unless you use a prebuilt package. Second, the protocol primitives are dependencies you do not control directly, which is why upgrade notes matter more here than in a typical web application.

## Installing Synapse standalone and registering a first user

The README does not inline install commands. It points to the documentation's standalone installation page, and the repository ships INSTALL.md and a docker/ directory alongside it. The package is published to PyPI as matrix-synapse, which is the name to use if you install from the Python package index.

The repository also carries a demo/ directory with start.sh, stop.sh and clean.sh scripts, which is the shortest thing to read if you want to see how a local instance is wired up before writing your own configuration. Beyond that, the README's own pointers are the installation page, the configuration options page, the federation page, the reverse proxy page and the upgrade page. There is no generate-config command shown in the README, so treat the documentation as the source for the exact invocation rather than any snippet you find elsewhere.

What the README does tell you is the shape of the work. You install the matrix-synapse package, you produce a homeserver.yaml, you put a reverse proxy in front of the server, and you decide whether to federate. Each of those has its own documentation page, and the reverse proxy page existing at all is the signal that a bare listener is not a deployment.

For a first real use, the goal is a server you can reach from a client. Once the server is running, the Admin FAQ is the README's recommended starting point for the problems that come up in the first week, and the community room #synapse:matrix.org is where installation questions go. Bug reports and feature requests go to GitHub issues; support requests do not.

## Federation is the feature and the operational burden

A Synapse server is not useful in isolation for long. The point of Matrix is that your users reach everyone else, and that means federation: your server exchanges events with remote servers, verifies their signatures, and resolves room state across the network. The README links a dedicated federation configuration page, which is a signal in itself. Federation is not a checkbox.

It also constrains your infrastructure in ways a closed chat server does not. Your server needs a stable public identity, TLS certificates that remote servers can validate, and a reverse proxy in front of it; the README links a reverse proxy page for exactly this reason. The service-identity dependency is present specifically so SSL certificates for IP addresses validate, which tells you how much of the security model rests on correct TLS configuration. Get the proxy wrong and federation fails in ways that look like the remote server being down.

This is the honest trade-off of self-hosting a federated protocol. You gain control of your data and the ability to talk to a network you do not own. You take on certificate management, DNS, proxy configuration and a server that other people's servers will judge by its behaviour.

## Where Synapse is the wrong choice

The clearest case against Synapse is a small team that wants chat and nothing else. Element's own README steers that audience to ESS Community, described as the free Matrix distribution tailored to small- and mid-scale, non-commercial community use cases, which ships a full Matrix stack rather than a single homeserver. If you install Synapse standalone, you are assembling that stack yourself: database, reverse proxy, TLS, and the operational habits to keep them running.

A second case is any deployment that needs commercial support with SLAs. The README states plainly that Element provides no support without a subscription, and that enterprise support comes with ESS. A bare Synapse install has community support through the #synapse:matrix.org room and the Admin FAQ, and bug reports go to GitHub issues, but there is no queue, no response time and no escalation path.

The third case is subtler. If your requirement is a chat platform with a fixed feature set and no federation, the Matrix protocol's flexibility is cost without benefit. Federation, event signing and room state resolution are work your server does on every message, and you pay for it whether or not you ever talk to another homeserver.

## How Synapse compares with a managed Matrix host

The realistic alternative is not another homeserver implementation, it is not running one. A managed Matrix hosting provider gives you a domain, an admin panel and someone else to call when federation breaks. The approach differs at the level of responsibility: with Synapse you own the homeserver.yaml, the signing key, the database and the upgrade window; with a managed host you own an account and a support ticket.

The second alternative, for organisations already invested in Element's tooling, is ESS Pro or ESS TI-M. These are distributions built around Synapse with commercial support, and the TI-M edition targets the German TI-Messenger and ePA specifications from Gematik. Choosing ESS over a bare install is choosing a supported configuration over a supported component.

What none of these alternatives change is the protocol. A managed host still runs a Matrix homeserver, and your users still federate. The decision is about who operates the server, not about what the server speaks.

## Licence, upgrade cost and what to check before you commit

Synapse is dual-licensed by Element Creations Ltd. You may use it free under the GNU Affero General Public License, version 3 or later, or under a paid Element Commercial License. The AGPL is a network copyleft licence: if you run modified Synapse as a service for other people, the licence's terms reach your modifications. The commercial licence exists as the alternative for organisations that cannot or will not accept that. The repository carries LICENSE-AGPL-3.0 and LICENSE-COMMERCIAL, and the README gives licensing@element.io as the contact for purchasing a commercial licence. This is a description of what the files say, not legal advice; the terms themselves govern.

Upgrade cost is real and the project treats it as such. There is a dedicated UPGRADE.rst in the repository and an upgrade page in the documentation, and releases arrive on a roughly weekly cadence, with v1.161.0 on 2026-09-15 and v1.162.0rc1 on 2026-09-22. Release candidates appear before the stable release, so there is a preview window if you want it. The changelog lives in CHANGES.md, and changelog.d/ holds fragments for unreleased changes.

The practical check before adopting is to read the upgrade notes for the releases between the version you install and the version you plan to run, and to confirm your Python version satisfies the >=3.10.0,<4.0.0 bound in pyproject.toml. The last push to the repository was on 2026-09-22.

## Conclusion

Adopt Synapse if you need a Matrix homeserver you control and can afford to operate it, or if you want the reference implementation that the wider Matrix ecosystem is tested against. Do not adopt it if you want a turnkey chat product, since Element points small teams at ESS Community instead. Before committing, read the standalone installation page and the upgrade notes, and decide which of the two licences applies to your deployment.

## FAQ

### What exactly is Synapse?

Synapse is an open source Matrix homeserver implementation written and maintained by Element. It is the server side of the Matrix protocol: it stores accounts, rooms and message history, and federates with other homeservers. The package is published as matrix-synapse on PyPI.

### How do I install Synapse?

The README points to the standalone installation page in the Synapse documentation rather than listing steps inline. The package is on PyPI as matrix-synapse, and the repository also ships INSTALL.md and a docker/ directory. The officially supported deployment path is the Element Server Suite, not a bare install.

### Does Synapse need a reverse proxy and TLS certificates?

The documentation has a dedicated page on using a reverse proxy with Synapse, and a separate page on federation configuration, which indicates both are expected in a real deployment. The dependency list includes service-identity specifically for validating SSL certificates for IP addresses.

### What licence is Synapse released under?

It is dual-licensed by Element Creations Ltd: free under the GNU Affero General Public License version 3 or later, or under a paid Element Commercial License. The repository contains LICENSE-AGPL-3.0 and LICENSE-COMMERCIAL, and the README lists licensing@element.io for commercial licensing.

### Does Element provide support for Synapse?

The README states there is no support from Element unless you have a subscription. Enterprise support with SLAs comes with an Element Server Suite subscription; otherwise support is community-based through the #synapse:matrix.org room and the Admin FAQ, with GitHub issues reserved for bug reports and feature requests.

## Sources

- [element-hq/synapse on GitHub](https://github.com/element-hq/synapse)
- [License: AGPL-3.0](https://github.com/element-hq/synapse/blob/develop/LICENSE)
- [Project website](https://element-hq.github.io/synapse)
- [README](https://github.com/element-hq/synapse/blob/develop/README.md)
- [Releases](https://github.com/element-hq/synapse/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/element-hq-synapse