diff --git a/README.md b/README.md
new file mode 100644
index 0000000..a28aeca
--- /dev/null
+++ b/README.md
@@ -0,0 +1,48 @@
+# Modular Bot Framework for Telegram (MBFT)
+Modular bot framework for telegram (MBFT for short) allows you to quickly create stable, modular and highly customizable bots.
+The concept comes from the original project created for Twitch chat that has shown its high stability (it has worked for over 10 months without a single crash).
+Now it is being rewritten for Telegram to serve many different purposes.
+
+## Installing and running the bot
+
+The installation can be easily done by cloning this repository and providing the Telegram bot token using the config/token file.
+In commands, it is done like this:
+```bash
+# cloning the repo
+git clone http://109.86.70.81:3000/dymik739/modular-bot-framework-for-telegram
+cd modular-bot-framework-for-telegram/
+
+# creating "config" folder and providing a token
+mkdir config/
+printf "YOUR_AUTH_TOKEN" > config/token
+
+# running the bot
+python3 main.py
+# or, using the screen utility:
+screen -S mbft python3 main.py
+```
+
+## Writing modules (for modVM v1)
+
+To start making your module, you need to create a folder in the modules/ directory and give it a unique name (just like with any other folder).
+After that, you need to create two files: for code and for metadata.
+
+Firstly, you want to make a file called "meta.json" - it will let the module loader know where you placed your code as well as some other useful metadata. Let's look at a sample meta.json file:
+```
+{
+    "index_file": index.py, # locates your source code; index.py by default
+    "start_on_boot": true, # tells mod loader to start your module automatically; false by default
+    "version": 1, # this points to the specific version of modVM your code needs to run; 1 by default
+    "alias": "testapp" # adds an alias to your module which can be later specified in control commands
+}
+```
+
+After that you can start writing your code in the index.py file; every code is different, but there are some generic rules to understand and follow:
+- your code receives message that can be accessed at self.MESSAGE
+- message text can be found at self.MESSAGE.text
+- to send a responce, you need to write a string with responce text to self.RESPONCE
+- you can use modules already available to you (json, codecs); please, try to avoid importing unneccesary modules
+- if you need to access files amd folders in your module dicertory, you can easily do so by using self.path + "filename"; self.path always contains your current folder name
+- please, avoid using time.sleep() in any scenario; modules are syncronous, so usage of this method will stall the entire bot
+
+If you want to submit your code, please check if it works by running the bot and testing the output; if you want to submit the code for someone to do more work on it, you should set "start_on_boot" to "false" in meta.json file (the same should be done for testing/unstable modules)