diff --git a/.gitignore b/.gitignore
index 70cebd19289..b1be96247a3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,3 +1,6 @@
+.vagrant
+/dapps
+
 # emacs
 *~
 
diff --git a/.npmignore b/.npmignore
index cd75c6170bf..6579415ef23 100644
--- a/.npmignore
+++ b/.npmignore
@@ -1,5 +1,8 @@
+.vagrant
+
 # Demo
 demo
+dapps
 
 # scripts
 scripts
diff --git a/README.md b/README.md
index 9305a1acde1..d009d2b8e33 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,51 @@
 # Agoric Javascript Smart Contract Platform
 
-## Getting Started
+## Prerequisites
+
+### Vagrant
+
+To run a standardized Linux distribution with all the required development tools, you probably want [Vagrant](https://www.vagrantup.com/docs/):
+
+```sh
+vagrant up --provider=docker
+# or
+vagrant up --provider=virtualbox
+# then
+vagrant ssh
+```
+
+The Vagrant setup has synchronized filesystem access with the workspace directory on your host system, so you can use your favourite IDE to modify the files, and just run Linux commands on the SSH connection.
+
+
+### Developing on the current OS
+
+If you don't use Vagrant, you can develop on your own local operating system.
 
 NOTE: You will need Go 1.12 or newer to run the Agoric VM.
 
 ```sh
 # Install the agoric devtool.
-# NOTE: If you can't do this, use `npx agoric` each time you see `agoric`
 npm install -g agoric
+```
+
+or:
+
+```sh
+# Run the agoric devtool.
+npx agoric [...options]
+```
+
+## Your first Agoric Dapp
+
+Here is a simple script for how to get started.
+
+```sh
+cd dapps
 # Initialize your dapp project.
-agoric init my-dapp
+# Note: Change the `demo` name to something meaningful.
+agoric init demo
 # Go to its directory.
-cd my-dapp
+cd demo
 # Install Javascript/Go dependencies.
 agoric install
 # Run the local vat machine.
diff --git a/Vagrantfile b/Vagrantfile
new file mode 100644
index 00000000000..0b90c31b1ae
--- /dev/null
+++ b/Vagrantfile
@@ -0,0 +1,94 @@
+# -*- mode: ruby -*-
+# vi: set ft=ruby :
+#
+# Vagrant box for Debian with cosmic-swingset dependencies
+#
+# use one of:
+#  vagrant up --provider=docker
+#  vagrant up --provider=virtualbox
+
+NODE_VERSION = "12.x"
+GO_VERSION = "1.12.7"
+
+CURRENT_DIR = File.dirname(__FILE__)
+
+$script = <<SCRIPT
+
+export DEBIAN_FRONTEND=noninteractive
+
+apt-get update && apt-get install -y --no-install-recommends \
+    apt-transport-https \
+    ca-certificates \
+    unzip \
+    curl \
+    gnupg2 dirmngr \
+    software-properties-common \
+    vim
+
+echo "Installing Node.js #{NODE_VERSION}"
+curl -sL https:/deb.nodesource.com/setup_#{NODE_VERSION} | bash -
+# apt-get install -y nodejs build-essential git
+
+echo "Installing Go #{GO_VERSION}"
+curl https://dl.google.com/go/go#{GO_VERSION}.linux-amd64.tar.gz > go#{GO_VERSION}.linux-amd64.tar.gz
+tar -C /usr/local -zxf go#{GO_VERSION}.linux-amd64.tar.gz
+cat > /etc/profile.d/99-golang.sh <<\EOF
+GOROOT=/usr/local/go
+GOPATH=\\\$HOME/go
+PATH=\\\$GOPATH/bin:\\\$GOROOT/bin:\\\$PATH
+export GOROOT GOPATH
+EOF
+
+apt-get update && apt-get install -y nodejs build-essential git rsync build-essential
+
+cd /vagrant && npm install -g .
+echo "Enjoy! :)"
+SCRIPT
+
+def get_ipaddr(hostname, default)
+  return Socket::getaddrinfo(hostname, nil)[0][3]
+  rescue SocketError
+    return default
+end
+
+Vagrant.configure("2") do |config|
+    config.vm.box = "debian/contrib-stretch64"
+    config.vm.hostname = "dev-agoric"
+
+    private_network_ip = get_ipaddr(config.vm.hostname, "10.10.10.11")
+    config.vm.network "private_network", ip: private_network_ip
+
+    config.vm.provision "shell", inline: $script
+    config.vm.provision "shell", inline: "echo 'cd /vagrant' >> .bash_profile", privileged: false
+
+    config.vm.post_up_message = \
+      "The private network IP address is: #{private_network_ip}\n\n" \
+      "To customize, set the host called '#{config.vm.hostname}'\n" \
+      "to the desired IP address in your /etc/hosts and run \n" \
+      "'vagrant reload'!\n"
+
+    config.vm.provider :virtualbox do |vb|
+      vb.name = "dev-agoric-vb"
+    end
+
+    config.vm.provider :docker do |docker, override|
+      override.vm.box = nil
+      docker.build_dir = "docker"
+      docker.build_args = ['-t', 'agoric/devtools:local']
+      docker.name = "dev-agoric-docker"
+      docker.ports = [
+	'127.0.0.1:8000:8000',
+	'127.0.0.1:9229:9229',
+      ]
+      docker.remains_running = true
+      docker.has_ssh = true
+      docker.create_args = ['--tmpfs', '/tmp:exec', '--tmpfs', '/run',
+			    '-v', '/sys/fs/cgroup:/sys/fs/cgroup:ro',
+#          '--volume=ag-solo-state:/vagrant/cosmic-swingset/solo',
+#          '--volume=ag-setup-cosmos-chains:/vagrant/cosmic-swingset/chains',
+#          '--volume=ag-cosmos-helper-state:/root/.ag-cosmos-helper',
+			    '--privileged=true',
+#			    '-v', '/var/run/docker.sock:/var/run/docker.sock',
+	]
+    end
+end
diff --git a/docker/Dockerfile b/docker/Dockerfile
new file mode 100644
index 00000000000..f63dae1b924
--- /dev/null
+++ b/docker/Dockerfile
@@ -0,0 +1,28 @@
+FROM debian:stretch
+# MAINTAINER Tasos Latsas "tlatsas@kodama.gr"
+LABEL maintainer="mfig@agoric.com"
+
+RUN apt-get update \
+    && apt-get install -y init openssh-server sudo curl python python3-venv python3-dev \
+    && apt-get clean
+
+RUN useradd --create-home --shell /bin/bash vagrant
+RUN echo root:vagrant | chpasswd
+RUN echo vagrant:vagrant | chpasswd
+
+RUN mkdir -m 0700 /home/vagrant/.ssh
+RUN curl https://github.com/raw/hashicorp/vagrant/master/keys/vagrant.pub \
+    > /home/vagrant/.ssh/authorized_keys
+RUN chown -R vagrant:vagrant /home/vagrant/.ssh
+RUN chmod 0600 /home/vagrant/.ssh/authorized_keys
+
+RUN sed --regexp-extended --in-place \
+    's/^session\s+required\s+pam_loginuid.so$/session optional pam_loginuid.so/' \
+    /etc/pam.d/sshd
+
+RUN echo 'vagrant ALL=(ALL) NOPASSWD: ALL' > /etc/sudoers.d/01_vagrant
+RUN chmod 0400 /etc/sudoers.d/01_vagrant
+
+RUN ln -sf /vagrant/cosmic-swingset /usr/src/app
+
+CMD ["/sbin/init"]