Develop Inside Docker With VS Code Remote Containers Without Local Drift

Local environment drift is the real problem. A teammate runs Node 20, you run 18, the linter needs a system library that isn’t on your laptop, and CI fails for reasons you can’t reproduce. The useful takeaway with VS Code Remote - Containers is to keep your source files on the host but run the editor server, extensions and terminal inside a Docker container defined by the project. You get a reproducible toolchain without changing how you edit.

How Remote - Containers attaches VS Code to a container

Remote - Containers is a VS Code extension that installs a small server into a container. When you open a folder, VS Code builds or reuses a container from a definition in the repo, mounts the folder into the container, and forwards the UI over a local socket. Extensions run inside the container, so they see the container’s OS, PATH and installed tools, not the host’s.

A dev container is described by .devcontainer/devcontainer.json at the project root. The file tells VS Code which image or Dockerfile to use, where to mount the workspace, which ports to expose and what commands to run after creation.

Worked configuration for a Node app

Create the directory .devcontainer next to your project root and add devcontainer.json. The example below uses a Dockerfile in the repo root and forwards port 3000.

{
  "name": "myapp-node",
  "dockerFile": "../Dockerfile",
  "workspaceFolder": "/workspace",
  "forwardPorts": [3000],
  "customizations": {
    "vscode": {
      "extensions": [
        "dbaeumer.vscode-eslint",
        "esbenp.prettier-vscode"
      ]
    }
  },
  "postCreateCommand": "npm ci"
}

With this file present, open the folder in VS Code and run the Command Palette command Remote-Containers: Reopen in Container. VS Code will build the image if needed, create a container, mount the project into /workspace, install the listed extensions inside the container, run npm ci, and reconnect the window.

Run the check from the integrated terminal inside VS Code. With Docker Desktop or a compatible Docker engine running on the host, docker ps should list a container for the workspace. The bottom-left status bar should show Dev Container: myapp-node. That indicator is the practical signal that the editor server is inside the container, not on the host.

Limits you need to plan for

Startup is slower than local. The first open builds the image and installs extensions inside the container. Subsequent opens reuse the container but still incur mount and server startup time.

Extensions that rely on native host binaries will not work unless those binaries are installed in the container image. Linters, debuggers and language servers run in the container context, so they need their dependencies there.

PATH and global tools differ. Scripts that assume a globally installed CLI on the host will fail inside the container. Install required tools in the Dockerfile or via postCreateCommand so they are present in the container environment.

File binding matters. The workspace folder is bind-mounted from the host. If workspaceFolder is misconfigured or the mount is read-only, edits appear to succeed locally but are not visible to processes inside the container, or vice versa.

Common mistakes and how to avoid them

Forgetting port forwarding. If your app listens on 3000 and you do not list it in forwardPorts, VS Code will not automatically open the preview and you may need to manually map ports. Add the port to the array and VS Code will prompt to open it.

Assuming the container is up to date. Changes to Dockerfile or devcontainer.json require a rebuild. Use the Command Palette command Remote-Containers: Rebuild Container after changing the image definition, otherwise you continue using an outdated environment.

Docker daemon not running. If Docker Desktop or the Docker engine is stopped, the reopen command fails with a connection error and no container is created. Ensure the daemon is running before opening the folder.

Mixing host and container tools. Running npm in an external terminal uses the host Node. Always use the VS Code integrated terminal when inside a dev container to guarantee commands execute in the container.

These constraints are manageable when the container definition is treated as part of the project. The payoff is a consistent environment for the team without requiring everyone to install system packages locally.