Dev Containers

What it is and why it exists

A Dev Container is a container environment for developing an application. It is not necessarily the package you deploy. It adds development metadata to a container image or Docker Compose project: how an editor connects, where the workspace lives, which ports to forward, and which commands to run after creation.

It fixes a problem of scattered environment definitions. With only a README, installation steps diverge by operating system, execution order, and date. Once the definition lives in the repository, a tool can create a local environment, cloud workspace, or CI job from the same declaration. That reduces variation; it does not make builds byte-identical when tags, Features, registries, and hosts can change.

You meet Dev Containers when a project needs a particular runtime, system package, database, or set of editor extensions. If a mature version manager is enough, the container’s build, disk, and permission costs may not pay off. Hardware devices, desktop applications, and complex corporate networks also require you to check what the implementing tool can pass through from the host.

How it works

The specification normally reads .devcontainer/devcontainer.json under the repository root; it also accepts .devcontainer.json at the root. The configuration chooses a base: refer to an image, point build at a Dockerfile, or select services with dockerComposeFile. All three describe a development environment. The Compose form also uses service to name the main service to which the editor and lifecycle commands connect.

The creating tool parses the file, substitutes variables such as ${localEnv:...}, and combines repository settings with image metadata and metadata from each Dev Container Feature . A Feature is a reusable installation unit, commonly a devcontainer-feature.json plus an installation script. It executes code while the image is built, so review its source and version as you would any build dependency.

After an environment is created for the first time, commands inside the container run in this order: onCreateCommand, updateContentCommand, then postCreateCommand. Resuming an existing container runs postStartCommand; every successful tool attachment runs postAttachCommand. initializeCommand is different: it runs where the source is located on the host and may run more than once in one session.

These properties are lifecycle commands . A string value runs through /bin/sh; an array invokes the program directly without a shell. Members of an object value run in parallel, and every member must succeed. A failure in one lifecycle stage prevents later stages from running.

containerUser selects the user for all operations in the container. The remote user , selected by remoteUser, runs lifecycle scripts and the processes launched by an editor or supporting tool. If remoteUser is absent, it defaults to the container user. Keeping the two separate lets an entrypoint use one identity while ordinary development processes use another.

containerEnv enters the container environment at creation time and is visible to its entrypoint. remoteEnv is added to remote processes by the supporting tool and can change during the container’s lifetime. workspaceMount determines how the source enters the container, while workspaceFolder selects the working directory for remote processes. forwardPorts asks the tool to forward container ports to the user; it is not a Docker port-publishing rule.

Dev Containers keep Docker’s boundaries. A bind mount still exposes a host path. Mounting the Docker socket usually gives the container control of the host’s Docker engine, while privileged and extra capabilities expand access further. A Dev Container is primarily environment management, not a security sandbox for untrusted code.

Examples

Start with one image

This configuration selects a Node 24 image and uses its node account for both container operations and remote tools. The array form of postCreateCommand bypasses the shell. The port attribute only tells a supporting tool what to do with port 3000. Because the configuration is committed, changes to environment permissions and setup behavior appear in code review.

The inspection script reads the committed configuration rather than a separately maintained description. It proves that the JSON parses and exposes a few important fields. A publication gate should still run devcontainer build or devcontainer up; only a real build resolves the combined image, Feature, user, and mount behavior.

Fail fast during creation

The first configuration calls this creation script. It checks the runtime before project setup; the example prints a short marker instead of installing anything, so it stays self-contained. A real Node project would run npm ci after the check and commit its package-lock.json.

const expectedMajor = 24;
const actualMajor = Number(process.versions.node.split(".")[0]);

if (actualMajor !== expectedMajor) {
  throw new Error(`expected Node ${expectedMajor}, got ${process.version}`);
}

console.log(`runtime=${process.version}`);
console.log("setup=ready");

runtime=v24.14.0
setup=ready

A failure stops later lifecycle stages instead of being hidden behind || true. Keeping the setup in a source file is easier to test and review than extending one shell string indefinitely. If the tool must wait for setup before attaching, set waitFor: "postCreateCommand" explicitly. The default wait point is updateContentCommand, so attachment need not wait for postCreateCommand.

Add a database with Compose

A multi-service environment puts the development container and database in one Compose project. app reaches PostgreSQL as db:5432; the database has no ports, so this does not publish it to the host. The health check makes depends_on wait until the database accepts connections rather than only until its container process starts.

services:
  app:
    image: node:24-bookworm-slim
    user: node
    command: sleep infinity
    volumes:
      - ..:/workspace
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:17-alpine
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: app
      POSTGRES_PASSWORD: local-only
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app -d app"]
      interval: 2s
      timeout: 2s
      retries: 10
    volumes:
      - postgres-data:/var/lib/postgresql/data

volumes:
  postgres-data:

{
  "name": "node-with-postgres",
  "dockerComposeFile": "compose.yaml",
  "service": "app",
  "workspaceFolder": "/workspace",
  "remoteUser": "node",
  "shutdownAction": "stopCompose",
  "forwardPorts": [3000]
}

docker compose -f .devcontainer/compose.yaml config --quiet
docker compose -f .devcontainer/compose.yaml config --services

db
app

docker compose config --quiet validates and resolves the Compose file; the second command lists services in dependency order. That does not prove the database can start. CI must create the environment and make a real connection from app. The sample password belongs only to a disposable local database; production credentials must not enter this configuration.

Pitfalls

Further reading

• Development Container Specification
• devcontainer.json metadata reference
• Dev Container Features specification
• Dev Container lockfile specification
• Dev Container CLI
• VS Code Dev Containers documentation