diff --git a/README b/README
new file mode 100644
index 0000000..9401251
--- /dev/null
+++ b/README
@@ -0,0 +1,53 @@
+nbd-proxy
+=========
+
+Prototype javascript+websocket NBD server; this code demonstrates a javascript
+NBD implementation connected to the kernel nbd device over a websocket.
+
+There are two components here:
+
+  nbd-proxy: a little binary to initialise a nbd client, connected to a
+             unix domain socket, then proxy data between that socket and
+             stdio. This can be used with a websocket proxy to expose
+             that stdio as a websocket.
+
+  nbd.js:    a javascript implementation of a NBD server.
+
+Running
+-------
+
+You'll need a websocket proxy This connects the nbd-proxy
+component to a websocket endpoint.
+
+For experimentation, I use the `websocketd` infrastrcture to expose the
+websocket endpoint, plus serve the static HTML+js client:
+
+    git clone https://github.com/joewalnes/websocketd
+    (cd websocketd && make)
+
+    sudo websocketd/websocketd --port=8000 --staticdir=web --binary ./nbd-proxy
+
+Note that this type of invocation is very insecure, and intended just for
+experimentation. See the Security section below.
+
+For real deployments, you want your websocket-enabled service to run
+nbd-proxy, and connect its stdio to a websocket, running in binary mode. Your
+web interface will interact with this using an instance of the NBDServer object
+(defined in web/js/nbd.js):
+
+    var server = NBDServer(endpoint, file);
+    server.start();
+
+- where endpoint is the websocket URL (ws://...) and file is a File object. See
+web/index.html for an example.
+
+Security
+--------
+
+This code allows potentially-untrusted clients to export arbitrary block
+device data to your kernel. Therefore, you should ensure that only trusted
+clients can connect as NBD servers.
+
+There is no authentication or authorisation implemented in the nbd proxy. Your
+websocket proxy should implement proper authentication before nbd-proxy is
+connected to the websocket endpoint.