Tuwunel: the Rust Matrix homeserver that replaces Synapse and migrates conduwuit databases in place

What Tuwunel replaces, and for whom

Tuwunel is a Matrix homeserver, the server side of the Matrix protocol that stores rooms, messages and account data for clients such as Element. The README positions it as something you can use "instead of Synapse with your favorite client, bridge or bot", and it is written entirely in Rust. That matters less as a language preference and more as an operational one: the project describes itself as a scalable, low-cost, community-driven alternative, and the deployment surface reflects that, with Docker images, static binaries, deb and rpm packages, AUR packages, an Alpine package, a Gentoo ebuild and a Nix package and NixOS module.

The audience is narrower than "anyone who wants chat". Tuwunel is for people who already intend to run a Matrix homeserver, or who are running one and want to move. The README states it is the official successor to conduwuit after that project reached stability, and that it is used by companies with full-time staff working on it, primarily sponsored by the government of Switzerland, where the README says it is deployed for citizens. Those are claims about the project's backing, not about its code quality, but they do tell you the project expects production operators rather than hobbyists.

The migration table is the clearest statement of who this is for. conduwuit, a fork of conduwuit, and Conduit all migrate, with the database migrating in place on first boot. Synapse does not, and the README points at issue #2 as the place to follow that work. If you are on Synapse, Tuwunel is not a drop-in replacement today.

Rust, RocksDB and a workspace split into src/* crates

The repository is a Cargo workspace. Cargo.toml declares members as src/* with default-members the same, so the server is assembled from several crates under src rather than one monolithic binary crate. The workspace pins edition 2024 and rust-version 1.95.0, which is a hard floor: you cannot build this with an older toolchain, and rust-toolchain.toml in the repository root is the file that pins what the project itself builds with.

The storage layer is RocksDB, which is visible in the repository topics and in the migration table, where Conduit's RocksDB database is described as migrating in place on first boot. That is the mechanism behind the migration story: compatible on-disk layout rather than an export and import step.

The HTTP layer is axum 0.8 with axum-extra and axum-server, plus a forked axum-server-dual-protocol pinned to a specific revision in the workspace dependencies. Dual protocol here is what lets the server speak both the client-server API on port 8008 and federation on 8448 through the same listener, which is why the Caddy example in the README proxies both tuwunel.me and tuwunel.me:8448 to localhost:8008. Password hashing uses argon2. TLS uses aws-lc-rs. None of this is exotic, and that is the point: the dependency list reads like a deliberate set of maintained Rust components rather than a research project.

What the README does not document is the internal data flow, the request path, or how federation state is cached. If you need that level of detail before adopting, the book at matrix-construct.github.io/tuwunel is the place to look, not the README.

Install Tuwunel with Docker and register the first admin user

The README's getting started list gives several install routes. The fastest is the published image, either from DockerHub as jevolk/tuwunel:latest or from GHCR as ghcr.io/matrix-construct/tuwunel:latest. Both are named in the README, so either pull command is the documented one.

docker pull ghcr.io/matrix-construct/tuwunel:latest

Configuration starts from tuwunel-example.toml in the repository root. The README states that server_name and database_path must be configured, and that most users deploying via Docker or a distribution package should follow the appropriate guide in the deploying documentation instead of the summary. It also suggests configuring a secret registration_token and setting allow_registration = true.

The README gives one strong warning about server_name: avoid a subdomain, because you can delegate later with a .well-known file but you can never change your server_name. Treat that line as the single most consequential decision in the setup.

TLS is normally handled by a reverse proxy. The README's Caddy example proxies the server name and port 8448 to localhost:8008, and serves a static Element build from /var/www/element:

tuwunel.me, tuwunel.me:8448 {
    reverse_proxy localhost:8008
}
web.tuwunel.me {
    root * /var/www/element/
    file_server
}

Reload Caddy with caddy reload --config /etc/caddy/Caddyfile. Then start the server, connect a client, and register a username. The README states the first registration is granted server admin. If you leave registration open without a token, the first stranger to reach your server becomes its administrator.

Synapse migration is the gap, and the README says so

The migration table is unusually honest. conduwuit, conduwuit forks and Conduit are all marked as migrating, with the database migrating in place on first boot. Synapse is marked not yet, with a pointer to issue #2 and a note that it is planned and important. That is a real limitation, not a documentation gap: if you have a Synapse deployment with years of rooms and media, Tuwunel gives you no supported path to bring it across.

The conduwuit migration carries its own caveat. The README says support for migrating from conduwuit will be maintained for a minimum of one year, but likely indefinitely. A minimum is a minimum. If you are planning a migration that depends on that path staying available, one year is the number the project has committed to.

The other failure mode is server_name. Because it cannot be changed after the fact, a deployment that picks a subdomain and later wants the root domain is stuck with delegation rather than a rename. The README says this plainly, and it is the kind of constraint that is cheap to respect at setup and expensive to discover later.

Finally, the README claims full implementation of the Matrix specification "for all but the most niche uses". That phrasing is the project's own, and it is the right level of precision to expect: it does not enumerate which niche features are missing, so if your deployment depends on an unusual part of the spec, check the documentation before assuming.

Tuwunel vs Synapse, and where continuwuity fits

The obvious comparison is Synapse, the reference Matrix homeserver. The difference in approach is implementation and packaging, not protocol: Tuwunel is Rust, Synapse is Python, and Tuwunel's distribution story is a set of prebuilt artifacts (Docker images, static binaries, deb, rpm, AUR, Alpine, Gentoo, Nix) rather than a Python deployment you assemble yourself. The README also frames it as low-cost, which for an operator usually means memory and CPU per user rather than licence cost, since both are open source.

The practical difference today is migration direction. Tuwunel reads conduwuit, conduwuit-fork and Conduit databases in place. It does not read Synapse. So the comparison is not symmetric: moving from Synapse to Tuwunel is unsupported, while moving from a Conduit-lineage server to Tuwunel is the path the project built for.

Continuwuity is the other name that comes up in search, and this article cannot compare them, because the README and the repository files do not describe it. What the README does establish is that Tuwunel is the official successor to conduwuit, which is the lineage claim that matters when you are choosing between conduwuit-derived servers.

If you are deciding between Tuwunel and Synapse on features alone, the README is not the document to decide from. It gives the deployment routes and the migration matrix, and points at the book for everything else.

Licence, releases and what upgrades cost you

Tuwunel is Apache-2.0, declared in Cargo.toml and shown in the repository's licence badge. Apache-2.0 is a permissive licence with an explicit patent grant, and it imposes no copyleft obligation on your own code. That is a statement about the licence text, not legal advice; if you are redistributing a modified Tuwunel, read the licence and the NOTICE requirements yourself.

Release cadence is visible from the tags: v1.9.1 on 2026-09-12, v1.9.2 on 2026-09-21 and v1.9.3 on 2026-09-25, with the last push to main on 2026-09-28. That is a fast patch cadence, roughly weekly, and it is the main upgrade cost. A server that cuts releases this often expects operators to move, which means you want a deployment route that makes upgrading cheap. Distribution packages and container images are the two that do; a hand-built binary from source is the one that does not.

The workspace pins rust-version 1.95.0 and edition 2024, so any build from source needs a toolchain at or above that. The repository also carries a flake.nix, a default.nix and a nix/ directory, plus a Nix binary cache at https://cache.tuwunel.chat, which the README links from the NixOS guide. If you build from source on a distro without a package, that cache is the difference between a compile and a download.

Upgrade risk is concentrated in the database. Because migrations happen in place on first boot, a version that changes the on-disk format is not something you can roll back by reinstalling the previous binary. The README does not document rollback, so back up database_path before you upgrade.

Editorial conclusion

Adopt Tuwunel if you run a Matrix homeserver and want a Rust implementation you can install from Docker, Debian, RPM, Arch, Alpine, Gentoo or Nix packages, especially if you are already on conduwuit or Conduit, since the RocksDB database migrates in place on first boot. Do not adopt it if your deployment depends on importing an existing Synapse database, because that path is not implemented. Before committing, verify your server_name choice, since the README warns it can never be changed, and confirm your deployment route against the deploying guide rather than the impatient summary.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. matrix-construct/tuwunel on GitHub
3. Project website
4. README
5. Releases