Want to take your software engineering career to the next level? Join the mailing list for career tips & advice Click here


A Matrix homeserver written in Rust.

Subscribe to updates I use ruma

Statistics on ruma

Number of watchers on Github 628
Number of open issues 61
Average time to close an issue about 2 months
Main language Rust
Average time to merge a PR 5 days
Open pull requests 16+
Closed pull requests 8+
Last commit almost 3 years ago
Repo Created over 4 years ago
Repo Last Updated over 2 years ago
Size 699 KB
Homepage https://www.ruma.io/
Organization / Authorruma
Page Updated
Do you use ruma? Leave a review!
View open issues (61)
View ruma activity
View on github
Fresh, new opensource launches 🚀🚀🚀
Software engineers: It's time to get promoted. Starting NOW! Subscribe to my mailing list and I will equip you with tools, tips and actionable advice to grow in your career.
Evaluating ruma for your project? Score Explanation
Commits Score (?)
Issues & PR Score (?)


Build Status

Ruma is a Matrix homeserver written in Rust.

If you're interested in the project, please take a look at the Ruma website, follow ruma_io on Twitter and chat with us in #ruma:matrix.org on Matrix (also accessible via #ruma on the freenode IRC network.)


The goal of Ruma as a project is to provide a complete implementation of a Matrix homeserver, a Matrix identity server, a Matrix client library, and Matrix application services. This repository in particular aims to implement a Matrix homeserver. The Ruma homeserver will be packaged as a single executable for small-scale deployments, and as multiple executables for large deployments that need to scale different parts of the homeserver independently. Additional Matrix libraries used by Ruma can be found in the Ruma organization on GitHub.

Ruma is currently pre-alpha and cannot realistically be used from a standard Matrix client, but it's getting closer every week!

For a detailed view of which Matrix APIs are supported by Ruma so far, see the STATUS document.


Ruma includes a development setup using Docker. To install Docker, see the installation instructions for OS X, Linux, or Windows. (Note that both Docker and Docker Compose are needed, but the standard ways of installing include both.)

Note: docker-compose version 1.6 or higher and docker-engine version 1.10.0 or higher are required.

Cargo is the main entrypoint for development. Use the script/cargo shell script as you would normally use plain cargo. This will run the Cargo command inside a Docker container that has Rust and other dependencies already installed. It will automatically start a PostgreSQL database inside a container as well. The first time you run a command with script/cargo, it will take some time to download the Docker images.

To build Ruma, run script/cargo build --bin ruma. The application will be written to target/debug/ruma. You can also build and run Ruma in one step with script/cargo run --bin ruma. (When run via Cargo, arguments to ruma itself must come after two dashes, e.g. script/cargo run --bin ruma -- run.)

Nightly Rust

Ruma currently requires the nightly version of Rust because it uses the following unstable features, listed below with links to the GitHub issues tracking stabilization:

When all of these features are stabilized, Ruma will target stable Rust.

Developing without Docker

Docker is used to make everyone's life easier by pinning a compatible version of nightly Rust and managing test PostgreSQL databases without assuming anything about the host system. If you really want to avoid Docker, it's up to you to configure your development environment to match the assumptions made by code in Ruma. In particular, this means a version of the nightly Rust compiler that can compile Ruma given the current Cargo.lock and a PostgreSQL installation with suitable permissions available at the address and port used in src/test.rs. You can find the version of nightly Rust used in the Docker setup by looking at the Dockerfile for Ruma's development Docker image. Look at the line that installs rustup for the date. It will look something like this:

./rustup-init -y --no-modify-path --default-toolchain nightly-YYYY-MM-DD


To generate API documentation for Ruma, run script/cargo doc. Then open target/doc/ruma/index.html in your browser. Note that this documentation is for Ruma's internal Rust code, not the public-facing Matrix API. User-facing documentation will live on the Ruma website.


Ruma includes an integration test suite. Once Docker is installed, run script/cargo test to run the test suite.


Ruma requires a configuration file named ruma.json, ruma.toml, or ruma.yaml/ruma.yml written in JSON, TOML, or YAML, respectively. This file should be in the working directory ruma is executed from. Ruma will attempt to load the configuration file in that same order, stopping at the first one it finds. A configuration file would look something like this, in the JSON format:

  "version": "1",
  "domain": "example.com",
  "macaroon_secret_key": "qbnabRiFu5fWzoijGmc6Kk2tRox3qJSWvL3VRl4Vhl8=",
  "postgres_url": "postgres://username:password@example.com:5432/ruma"

The complete list of attributes in the configuration is as follows:

  • bind_address (string, default: The network address where the server should listen for connections.
  • bind_port (string, default: 3000): The network port where the server should listen for connections.
  • domain (string, required): The DNS name where clients can reach the server. Used as the hostname portion of user IDs.
  • macaroon_secret_key (string, required): The secret key used for generating Macaroons. Must be 32 cryptographically random bytes, encoded as a Base64 string. Changing this value will invalidate any previously generated macaroons, effectively ending all user sessions.
  • postgres_url (string, required): A PostgreSQL connection string for Ruma's PostgreSQL database.
  • version (string, required): The version of the Ruma configuration file format that this configuration represents. This field allows Ruma to make backwards-incompatible changes to the configuration file format over time without breaking existing deployments. Currently the only valid value is 1.


ruma 0.1.0
A Matrix homeserver.


    -h, --help       Prints help information
    -V, --version    Prints version information

    help      Prints this message or the help message of the given subcommand(s)
    run       Runs the Ruma server
    secret    Generates a random value to be used as a macaroon secret key

Before you run ruma run, make sure you have a configuration file in the working directory named ruma.json and that a PostgreSQL server is running and available at the location specified in the configuration file. Ruma will automatically create the database (if it doesn't already exist) and manage the database schema. You are responsible for providing Ruma with a valid PostgreSQL server URL and role that can perform these operations.


Ruma includes an HTTP endpoint to serve Swagger data at http://example.com/ruma/swagger.json (substituting the host and port of your Ruma server for example.com, of course.) Point a copy of Swagger UI at this URL to see complete documentation for the Matrix client API. Note that Ruma does not actually implement all these API endpoints yet.


See the CONTRIBUTING document.


Ruma is dedicated to my best friend, Tamara Boyens, who passed away in January 2017. She and I talked online for hours every day. She was a large part of my motivation in starting Ruma, because our online communication was where we spent the most time together after we both moved away from the city where we met, and we were always looking for a system that would fix our grievances with all the subpar choices we had for chatting.

Jimmy Cuadra



ruma open issues Ask a question     (View All Issues)
  • over 3 years Implementing Event storage and search with a timeseries database or a lucene indexed database
  • over 3 years Categorize issues by difficulty to help out new contributors
  • over 3 years Implement a rate-limiting middleware
  • almost 4 years Restructure folders and files in ruma
  • almost 4 years API: POST /account/3pid/email/requestToken
  • almost 4 years API: POST /register/email/requestToken
  • almost 4 years API: POST /account/password/email/requestToken
  • about 4 years CJK search
  • about 4 years Create test database and run migrations from Rust
  • about 4 years API: GET /rooms/:room_id/context/:event_id
  • about 4 years API: GET /admin/whois/:user_id
  • about 4 years API: GET /user/:user_id/rooms/:room_id/tags
  • about 4 years API: DELETE /user/:user_id/rooms/:room_id/tags/:tag
  • about 4 years API: PUT /user/:user_id/rooms/:room_id/tags/:tag
  • about 4 years API: GET /events
  • about 4 years API: POST /search
  • about 4 years API: POST /rooms/:room_id/invite
  • about 4 years API: GET /pushrules/:scope/:kind/:rule_id/actions
  • about 4 years API: PUT /pushrules/:scope/:kind/:rule_id/actions
  • about 4 years API: GET /pushrules
  • about 4 years API: GET /pushrules/:scope/:kind/:rule_id
  • about 4 years API: DELETE /pushrules/:scope/:kind/:rule_id
  • about 4 years API: PUT /pushrules/:scope/:kind/:rule_id
  • about 4 years API: GET /pushrules/:scope/:kind/:rule_id/enabled
  • about 4 years API: PUT /pushrules/:scope/:kind/:rule_id/enabled
  • about 4 years API: GET /pushers
  • about 4 years API: POST /pushers/set
  • about 4 years API: GET /thumbnail/:server_name/:media_id
  • about 4 years API: POST /upload
  • about 4 years API: GET /download/:server_name/:media_id
ruma open pull requests (View All Pulls)
  • Implement GET /directory/room/:room_alias
  • Add basic implementation for the /profile/:user_id/{...} endpoint.
  • Generate a m.room.aliases event when a new RoomAlias is created
  • Add basic implementation for the sync endpoint.
  • Add basic implementation for the tags endpoint.
  • Add basic implementation for local invites
  • WIP: Add implementation for the filter endpoint.
  • Add /publicRooms endpoint
  • Add temporary UIAuth provider
  • Add basic implementation for the presence endpoints.
  • Add /room/:room_id/state
  • Ensure valid json response
  • Add endpoints to retrieve state event's content from a room
  • WIP: Support media api, do some refactor and add API as unimplemented.
  • Add the packaging metadata to build the ruma snap
  • WIP: Merge api endpoints in join and add ban, unban and forget
ruma list of languages used
Other projects in Rust