Develop on a remote Docker host

Sometimes you may want to use the Dev Containers extension to develop inside a container that sits on a remote server. Docker does not support mounting (binding) your local filesystem into a remote dev container, so Visual Studio Code's default devcontainer.json behavior to use your local source code will not work. While this is the default behavior, in this section we will cover connecting to a remote host so that you can either use the Remote - SSH extension to open a folder on a remote host in a container, attach to any running container, or use a local devcontainer.json file as a way to configure, create, and connect to a remote dev container using a socket.

Connect using the Remote - SSH extension

If you are using a Linux or macOS SSH host, you can use the Remote - SSH and Dev Containers extensions together. You do not even need to have a Docker client installed locally. To do so:

1. Follow the installation and SSH host setup steps for the Remote - SSH extension.
2. Optional: Set up SSH key based authentication to the server so you do not need to enter your password multiple times.
3. Install Docker on your SSH host. You do not need to install Docker locally.
4. Follow the quick start for the Remote - SSH extension to connect to a host and open a folder there.
5. Create a devcontainer.json file.
6. Use the Dev Containers: Reopen in Container command from the Command Palette (F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P)).

The rest of the Dev Containers quick start applies as-is. You can learn more about the Remote - SSH extension in its documentation.

Connect using the Remote - Tunnels extension

You can use the Remote - Tunnels and Dev Containers extensions together to open a folder on your remote host inside of a container. You do not even need to have a Docker client installed locally. This is similar to the SSH host scenario above, but uses Remote - Tunnels instead. To do so:

1. Follow the Getting Started instructions for the Remote - Tunnels extension.
2. Install Docker on your tunnel host. You do not need to install Docker locally.
3. Follow the steps for the Remote - Tunnels extension to connect to a tunnel host and open a folder there.
4. Use the Dev Containers: Reopen in Container command from the Command Palette (F1, ⇧⌘P (Windows, Linux Ctrl+Shift+P)).

The rest of the Dev Containers quick start applies as-is. You can learn more about the Remote - Tunnels extension in its documentation.

Connect using the Docker CLI

This model only requires that a Docker Engine be running on a remote host that your local Docker CLI can connect to. While using the Remote - SSH and Remote - Tunnels extensions is easier and doesn't require the Docker CLI to even be installed locally, this model can be useful for situations where you already have a host you are connecting to from the command line. This approach is also useful if you are looking to attach to already running containers on this remote server.

A basic remote example

Setting up VS Code to attach to a container on a remote Docker host can be as easy as setting the Container Tools extension containers.environment property in settings.json and restarting VS Code (or reloading the window).

For example:

In fact, the Dev Containers: Clone Repository in Container Volume... command in the Command Palette (F1) uses this same technique. If you already have a devcontainer.json file in a GitHub repository that references an image or Dockerfile, the command will automatically use a named volume instead of a bind mount - which also works with remote hosts.

The second approach is to bind mount a folder on the remote machine into your container. This requires you to have access to the remote filesystem, but also allows you to work with existing source code on the remote machine.

Update the workspaceMount property in the example above to use this model instead:

After restarting VS Code (or reloading the window), you will now be able to attach to any running container on the remote host. You can also use specialized, local devcontainer.json files to create / connect to a remote dev container.

Tip: If this is not working for you but you are able to connect to the host using SSH from the command line, be sure you have the SSH agent running with your authentication key. If all else fails, you can use an SSH tunnel as a fallback instead.

Using the TCP protocol

While the SSH protocol has its own built-in authorization mechanism, using the TCP protocol often requires setting other Container Tools extension properties in your settings.json. These are:

If you do have login access, you can use a remote filesystem bind mount instead:

If you do have login access, you can use a remote filesystem bind mount instead: