Comprehensive guide for creating, editing, and validating devcontainer.json configuration files. Use when working with Development Container configurations for any scenario including creating new devcontainer.json files, modifying existing configurations, troubleshooting dev container issues, adding features or lifecycle scripts, configuring ports and environment variables, setting up multi-container environments with Docker Compose, or understanding devcontainer properties and their usage.
This skill provides comprehensive guidance for working with devcontainer.json files - the configuration files that define Development Containers. It covers all configuration scenarios (image-based, Dockerfile-based, and Docker Compose), property usage, common patterns, and validation.
Choose the appropriate base configuration:
1. Image-based - Use an existing container image:
assets/basic-image.jsonimage2. Dockerfile-based - Build from a custom Dockerfile:
assets/dockerfile-based.jsonbuild.dockerfile3. Docker Compose - Multi-container environments:
assets/docker-compose.jsondockerComposeFile, serviceassets/name, add features, configure customizationspostCreateCommand, postStartCommand, etc.forwardPorts and portsAttributes as neededscripts/validate.py to check for issuesFeatures extend container functionality. Add them using the features property:
{
"features": {
"ghcr.io/devcontainers/features/node:1": {
"version": "20"
},
"ghcr.io/devcontainers/features/github-cli:1": {},
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
}
}
Browse available features at: https://containers.dev/features
Use containerEnv for static, container-wide variables:
{
"containerEnv": {
"NODE_ENV": "development",
"API_URL": "http://localhost:3000"
}
}
Use remoteEnv for client-specific variables that may change:
{
"remoteEnv": {
"LOCAL_USER": "${localEnv:USER}"
}
}
Configure commands that run at different stages:
{
"onCreateCommand": "npm ci",
"updateContentCommand": "npm install",
"postCreateCommand": "npm run build",
"postStartCommand": "npm run dev"
}
Command formats:
&& and pipesForward ports with custom behavior:
{
"forwardPorts": [3000, 5432],
"portsAttributes": {
"3000": {
"label": "Application",
"onAutoForward": "openBrowser"
},
"5432": {
"label": "Database",
"onAutoForward": "silent"
}
}
}
Add extensions via customizations:
{
"customizations": {
"vscode": {
"extensions": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"
]
}
}
}
For debugging languages like C++, Go, Rust:
{
"capAdd": ["SYS_PTRACE"],
"securityOpt": ["seccomp=unconfined"]
}
For Docker-in-Docker:
{
"features": {
"ghcr.io/devcontainers/features/docker-in-docker:2": {}
},
"privileged": true
}
Mount additional directories or volumes:
{
"mounts": [
{
"source": "${localEnv:HOME}/.ssh",
"target": "/home/vscode/.ssh",
"type": "bind"
},
{
"source": "project-cache",
"target": "/workspace/.cache",
"type": "volume"
}
]
}
Control which user runs commands:
{
"containerUser": "vscode",
"remoteUser": "vscode",
"updateRemoteUserUID": true
}
containerUser: User for all container operationsremoteUser: User for dev tools/terminalsupdateRemoteUserUID: Match local user UID/GID on LinuxUse the validation script to check configurations:
python scripts/validate.py /path/to/devcontainer.json
The validator checks for:
Example output:
============================================================
Validation Results for: devcontainer.json
============================================================
❌ ERRORS:
- Must specify one of: 'image', 'build.dockerfile', or 'dockerComposeFile'
⚠️ WARNINGS:
- Missing 'name' property - recommended for UI display
❌ Validation failed with 1 error(s)
For detailed property information:
Use these references when:
Available variables for use in string values:
${localEnv:VAR_NAME} - Environment variable from host machine${containerEnv:VAR_NAME} - Environment variable from container${localWorkspaceFolder} - Local path to workspace${containerWorkspaceFolder} - Container path to workspace${localWorkspaceFolderBasename} - Workspace folder name${devcontainerId} - Unique container identifierDefault values: ${localEnv:VAR:default_value}
image, build.dockerfile, or dockerComposeFile)updateRemoteUserUID: true on LinuxcontainerUser and remoteUser appropriately0.0.0.0 not just localhostforwardPorts configurationportsAttributes settingsoverrideFeatureInstallOrder if dependencies exist