diff --git a/README.md b/README.md
new file mode 100644
index 0000000000000000000000000000000000000000..2b3b20cebc7877314b7746079f2a8df33e9248e9
--- /dev/null
+++ b/README.md
@@ -0,0 +1,64 @@
+
+# Matrix mod for Minetest
+
+
+This mod creates a bridge between a [Matrix](https://matrix.org) channel and the in-game chat.
+The code is shamelessly based on the [irc](https://github.com/minetest-mods/irc) mod and examples from [lua-matrix](https://github.com/aperezdc/lua-matrix).
+
+
+## Installing
+
+
+```bash
+cd <Mods directory> && git clone --recursive git@github.com:diggers-mt/minetest-matrix.git
+```
+
+### OS X
+
+```bash
+brew install lua@5.1
+luarocks-5.1 install lua-cjson
+brew install openssl
+luarocks-5.1 install cqueues CRYPTO_DIR=/usr/local/opt/openssl/ OPENSSL_DIR=/usr/local/opt/openssl #https://github.com/wahern/cqueues/wiki/Installation-on-OSX#via-brew
+luarocks-5.1 install luaossl CRYPTO_DIR=/usr/local/opt/openssl/ OPENSSL_DIR=/usr/local/opt/openssl
+export MATRIX_API_HTTP_CLIENT=luasocket
+```
+
+### Ubuntu
+
+Tested on 16.04.
+
+```bash
+apt-get install lua5.1 luarocks lua-sec
+luarocks install lua-cjson
+export MATRIX_API_HTTP_CLIENT=luasocket
+```
+
+You might need to prepend `sudo` to first and second commands
+
+You also need to add Matrix to your trusted mods if you haven't disabled mod security.
+
+```
+secure.trusted_mods = matrix
+```
+
+[wiki]: https://wiki.minetest.net/Installing_mods
+
+
+## Settings
+
+* `matrix.user`: Matrix username, for example `@minetestbot@matrix.org`
+
+* `matrix.password`: Password for Matrix user
+
+* `matrix.server`: Server to connect to, include http(s), `https://matrix.org`
+
+* `matrix.port`: Server port, default `8448`
+
+* `matrix.room_id`: Room to join, `room_id` in matrix. Always starts with `!`
+
+
+## License
+
+See `LICENSE.txt` for details.
+
diff --git a/description.txt b/description.txt
index d0de424f44ae30a9f4d08b60707cce5fc2822f3d..9565a95b07fcba033a5828b0ef7cd10cdf0fcc5c 100644
--- a/description.txt
+++ b/description.txt
@@ -1 +1 @@
-This mod creates a bridge between (multiple) Matrix channels and in-game chat!
+This mod creates a bridge between a Matrix channel and the in-game chat!