Limitations

There are several limitations that you need to keep in mind when working with Dev Containers.

Dev Containers on Windows

Dev Container images based on the Windows OS are not supported.

Creating Dev Containers from a VCS project

When you start a Dev Container from a VCS project, the following steps occur under the hood:

Build a Dev Container

The helper container for git clone is prepared.
The repository is cloned into the Docker volume.
The tmp working directory is created on the remote server.
The build context is extracted from the volume to the tmp directory.
Docker gets the context for the Dev Container building.
A temporary working directory is cleaned up afterward.

To avoid errors in the devcontainer.json properties, Docker file, and Docker-compose related to a mount process and relative paths, we list all the build steps and include a warning suggesting to check your Dev Container configuration.

Check the following warning example:

                    WARNING: Mount from /var/folders/0h/f3gs9sz96xdbqnp63t7bs4b80000gn/T/jb_devcontainer_sources_12dc6d53a2ae8fac66e0a54e76f501464151078046496127718/DevCont_templates/.devcontainer
                    to /workspaces is referenced to temporary folder used for build. This may lead to unexpected behaviour
                    or not working devcontainer. Please check that your devcontainer configuration is expected for
                    build from git repository.
                

Run Container inside the remote IDE

A scenario of creating a Dev Container from the running backend-client connection is not supported.

For example, you connected to your remote project using the SSH connection and you've added a devcontainer.json. There is no option to start a Dev Container from the created devcontainer.json file.

However, you can use the following procedure as a workaround:

Create a Dev Container on the remote machine

Create a Docker connection to SSH.
Install the Docker CLI locally.
On Windows, you can install it without the Docker desktop; we do not need the Docker daemon, we need only Docker CLI.
Commit all changes from the SSH machine to Git.
Create a Dev Container by using remote server and the git clone command.

XDG_* environment variables on the remote backend

The following environment variables are used by the remote backend IDE and cannot be reassigned in the devcontainer.json configuration file:

            XDG_CACHE_HOME
            XDG_CONFIG_HOME
            XDG_DATA_HOME
        

16 June 2025