diff --git a/embark/README.md b/embark/README.md
new file mode 100644
index 0000000000..7a0ed71dd0
--- /dev/null
+++ b/embark/README.md
@@ -0,0 +1,42 @@
+# embark-remix
+An Embark plugin that allows Remix to connect to a local DApp via [`remixd`](https://github.com/ethereum/remixd). This plugin serves a local copy of Remix IDE from the machine running the plugin or alternatively allows connection from the public [Remix IDE](https://remix.ethereum.org). The URL of the Remix IDE can be specified in the Embark plugin options, specified below.
+
+## Options
+To configure options for the `embark-remix` plugin, modify the `plugins` property of `embark.json` in the DApp.
+
+### How to use default options
+To pass no options to the plugin and use the defaults, simply use an empty object:
+```
+"plugins": {
+  "embark-remix": {}
+}
+```
+This will provide the default options to the plugin (shown below).
+
+### Available options
+The available options for this plugin are below. Default options are shown below. This is equivalent to passing an empty object `{}`.
+```
+"plugins": {
+  "embark-remix": {
+    "readOnly": false,
+    "remixIde": {
+      "protocol": "http",
+      "host": "localhost",
+      "port": 8088
+    }
+  }
+}
+```
+
+
+`readOnly` does not let Remix update the contents on the local filesystem. Default: `false`.
+`remixIde` specifies the URL that the Remix IDE will be served from. If this is a `localhost` URL, the plugin creates a server that is responsible for listening on this URL. Default: `(see above)`.
+
+If it is preferred to connect to the public Remix IDE at https://remix.ethereum.org, set the `remixIde` config to:
+```
+"remixIde": {
+  "protocol": "https",
+  "host": "remix.ethereum.org",
+  "port": false
+}
+```
\ No newline at end of file
diff --git a/embark/index.js b/embark/index.js
index a82d2ca027..67cfa91835 100644
--- a/embark/index.js
+++ b/embark/index.js
@@ -1,22 +1,67 @@
-/* global path */
-var httpServer = require('http-server')
-var remixd = require('remixd')
+const httpServer = require('http-server');
+const remixd = require('remixd');
+const path = require('path');
+const merge = require('merge');
+const colors = require('colors');
+
+const DEFAULT_OPTIONS = {
+  protocol: "http",
+  host: "localhost",
+  port: "8088"
+}
 
 module.exports = (embark) => {
-  var server = httpServer.createServer({
-    root: path.join(__dirname, '/node_modules/remix-ide')
-  })
+  // plugin options
+  const readOnly = embark.pluginConfig.readOnly || false;
+  const {protocol, host, port} = merge.recursive(DEFAULT_OPTIONS, embark.pluginConfig.remixIde);
+
+  // globals
+  const remixIdeUrl = `${protocol}://${host}` + `${port ? `:${port}` : ''}`;
+  const sharedFolder = path.join(__dirname, '../../');
+  const sharedFolderService = remixd.services.sharedFolder;
+  let server;
 
+  // setup HTTP server
+  if (['localhost', '127.0.0.1', '0.0.0.0'].includes(host)) {
+    server = httpServer.createServer({
+      root: path.join(__dirname, '../../node_modules/remix-ide')
+    });
+    server.listen(port, '127.0.0.1', function () {
+      embark.logger.info('Remix IDE (via embark-remix plugin) available at ' + colors.underline(remixIdeUrl));
+    });
+  } else {
+    embark.logger.info('embark-remix is set to connect to a Remix IDE at ' + colors.underline(remixIdeUrl));
+  }
+
+  // setup Embark service check
   embark.registerServiceCheck('Remix IDE', (cb) => {
-    return cb({name: 'Remix IDE (localhost:8080)', status: 'on'})
-  })
+    return cb({ name: `Remix IDE ${host}:${port}`, status: 'on' });
+  });
 
-  server.listen(8080, '127.0.0.1', function () {})
-  var router = new remixd.Router(65520, remixd.services.sharedFolder, (webSocket) => {
-    remixd.services.sharedFolder.setWebSocket(webSocket)
-    var sharedFolder = path.join(__dirname, '/../../')
-    remixd.services.sharedFolder.setupNotifications(sharedFolder)
-    remixd.services.sharedFolder.sharedFolder(sharedFolder)
+  // setup remixd shared folder service
+  const sharedFolderRouter = new remixd.Router(65520, sharedFolderService, { remixIdeUrl }, (webSocket) => {
+    sharedFolderService.setWebSocket(webSocket);
+    sharedFolderService.setupNotifications(sharedFolder);
+    sharedFolderService.sharedFolder(sharedFolder, readOnly);
   })
-  router.start()
+  const killRemixD = sharedFolderRouter.start();
+  const kill = () => {
+    if(server) server.close();
+    embark.logger.info(colors.red('embark-remix stopped'));
+    process.exit();
+  }
+
+  if (process.platform === 'win32') {
+    require('readline').createInterface({
+      input: process.stdin,
+      output: process.stdout
+    }).on('SIGINT', function () {
+      process.emit('SIGINT');
+    });
+  }
+  
+  process.on('SIGINT', kill); // catch ctrl-c
+  process.on('SIGTERM', kill); // catch kill
+  process.on('exit', killRemixD);
+
 }