diff --git a/README.md b/README.md
index b62a755d8..b53120918 100644
--- a/README.md
+++ b/README.md
@@ -55,3 +55,7 @@ When you open a Swift package (a directory containing a **Package.swift**) the e
 Press `F5` to run an executable and start debugging. If you have multiple launch configurations you can choose which launch configuration to use in the debugger view. 
 
 CodeLLDB has a version of `lldb` packaged with it and by default this is the version it uses for debugging. However, this version of `lldb` does not work with Swift. Fortunately, CodeLLDB allows you to choose an alternate version. The Swift extension will attempt to ascertain which version is required and give you the option to update the CodeLLDB configuration. 
+
+### Documentation
+
+* [Visual Studio Code Remote Development](docs/remote-dev.md)
\ No newline at end of file
diff --git a/docs/remote-dev.md b/docs/remote-dev.md
new file mode 100644
index 000000000..8634124af
--- /dev/null
+++ b/docs/remote-dev.md
@@ -0,0 +1,68 @@
+# Visual Studio Code Remote Development
+
+[VSCode Remote Development](https://code.visualstudio.com/docs/remote/containers) allows you to run your code and environment in a container. This is especially useful for Swift when developing on macOS and deploying to Linux. You can ensure there are no compatibility issues in Foundation when running your code.
+
+## Requirements
+
+As well as installing the Swift extension, you must install Docker on your machine to run the remote container in. See the [Visual Studio Code documentation](https://code.visualstudio.com/docs/remote/containers) for more details.
+
+Next, install the [Remote Development extension pack](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.vscode-remote-extensionpack) that contains extensions for working in remote environments in VSCode. If you only want to work with remote containers (and not use the SSH or WSL containers), you may want to only install the [Remote Development Container extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) instead.
+
+## Running in a container
+
+### Manual Setup
+
+VSCode requires a `.devcontainer` directory which defines the settings in `devcontainer.json` and optionally a `Dockerfile` defining the container to run in.
+
+First create the directory. Next, create `devcontainer.json` and insert the following:
+
+```json
+{
+    "name": "Swift 5.5",
+    "image": "swift:5.5",
+    "extensions": [
+      "sswg.swift-lang",
+    ],
+    "settings": {
+      "lldb.library": "/usr/lib/liblldb.so"
+    },
+    "forwardPorts": [8080]
+}
+```
+
+This defines the minimum settings required to run a Swift package in a remote container. Here's what each thing does:
+
+* `name`: Used to specify the name of the remote container.
+* `image`: The Docker container image to run. You can choose whichever version of Swift you like, including [nightlies](https://hub.docker.com/r/swiftlang/swift).
+* `extensions`: Extensions to install in your remote environment. You do not need to specify extensions' dependencies, such as LLDB.
+* `settings`: Override any settings for extensions. The above example sets the LLDB path to stop the Swift extension from attempting to set it up.
+* `forwardPorts`: Ports to enable forwarding for. You may want to include this if building a Swift server application for example.
+
+That's all you need to get a dev container working!
+
+#### Using a custom Dockerfile
+
+You may want to use a custom Docker container that's version controlled to make it easy to set up a development environment for you team. In `devcontainer.json` replace `image` with the following:
+
+```json
+{
+    "build": { "dockerfile": "Dockerfile" },
+    // ...
+}
+```
+
+This will use the `Dockerfile` provided in `.devcontainer`. Create that file and insert your custom Dockerfile. For example:
+
+```docker
+FROM swift:5.5
+```
+
+<!-- ### Automatic Setup
+
+VSCode allows you to automatically configure your project with a dev container. In the command palette (`F1`) choose **Remote-Containers: Add Development Container Configuration Files...** and choose Swift. -->
+
+### Running in a container
+
+Once you've set up your `.devcontainer`, in the command palette run **Remote-Containers: Reopen in Container**. VSCode will relaunch running in your remote container!
+
+For more details about running your project in a remote container, and the available configuration options, see the [Visual Studio Code documentation](https://code.visualstudio.com/docs/remote/remote-overview).
\ No newline at end of file