diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000000000000000000000000000000000000..97c65b70462922a09b760b7fd06c7c01a3dcb5eb
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,40 @@
+# Ring Nameservice
+
+Ring Nameservice is used to resolve easily memorable usernames to Ring IDs. Ring clients communicate with the Nameservice using HTTP.
+
+To run, make sure you have Solidity compiler `solc` installed.
+
+Instructions for Ubuntu:
+
+```
+sudo add-apt-repository ppa:ethereum/ethereum
+sudo apt-get update
+sudo apt-get install solc
+```
+Then do a `make` in the project root directory.
+
+
+You'll need to use Python 3.5+ to run the nameservice. If you already don't have tmux installed, do `pip install tmux`, and then:
+
+```
+python start_eth_cluster.py
+```
+
+
+
+Finally, make sure you have nodejs and npm install, do:
+```
+npm install
+sudo nodejs index.js
+```
+(we need sudo for Express server to listen on port 80)
+
+This will launch the HTTP server used to interface with the nameservice.
+Send a GET request to `name/<username>` to get its Ring ID. Send a POST request to `name/<username>` to register new username-RingID pair.
+
+
+Optionally, you can dump all username-RingID pairs to file using:
+```
+nodejs read_names.js
+```
+This will dump all the username-RingID pairs to `names.json` file.
\ No newline at end of file