Ruma is a Matrix homeserver. In order to understand what that means, you first need to understand Matrix.
Matrix is a protocol for communicating online.
Matrix-powered apps, called Matrix clients, have all the features you'd want and expect from a modern chat app: instant messaging, group chats, audio and video calls, searchable message history, synchronization across all your devices, and more.
To use a Matrix client, you create an account on a Matrix homeserver. Your Matrix homeserver is your hub into the Matrix network. It stores your account information and all your conversations. You can communicate with people on your own homeserver or people on other homeservers. When you communicate with people on other homeservers, your homeserver and the other homeservers involved synchronize the conversation history. This allows you to communicate with anyone in the Matrix network seamlessly, without ever thinking about which homeserver they connect to.
Ruma – Your home in Matrix.
If you want to build a Matrix client or bot, have a look at matrix-rust-sdk. It builds on Ruma and includes handling of state storage, end-to-end encryption and many other useful things.
For homeservers, bridges and harder-to-categorize software that works with
Matrix, you're at the right place. To get started, add
ruma to your
dependencies (as a git dependency if you want all of the latest improvements),
enable all Cargo features that seem relevant and run
cargo doc -p ruma --open. The
ruma crate re-exports all relevant things,
ruma-client, which you can use to make client-API calls to a Matrix
If you use the crates through crates.io, make sure to choose versions of
ruma-client that depend on the same / compatible versions of the other
crates (checking one, for example
ruma-common, is enough though). At the time
of writing the latest versions are
ruma 0.0.2 and
which can be used together.
If you're using the crates through git, just use the same
you want to control the exact version only through
Cargo.lock) for both.
This may seem a little convoluted, that's because it is. We're working on it.
¹ (better) support for the other APIs is planned
As of 2021-01-19, we support the vast majority of endpoints in all of the various Matrix APIs except the identity service API (if you want to help with that, have a look at the crate/ruma-identity-service-api label).
Minimum Rust version
Ruma currently requires Rust 1.45. In general, we will never require beta or nightly for crates.io releases of our crates, and we will try to avoid releasing crates that depend on features that were only just stabilized.
There are two exceptions to this:
- ruma-signatures (and hence ruma with the federation-api feature) since it depends on ring, which is only guaranteed to work on the latest stable.
- ruma-client depends on some I/O libraries (and also on ring, conditionally), so it is also only guaranteed to work on the latest stable.
*Note that all licence references and agreements mentioned in the Ruma README section above are relevant to that project's source code only.