Devcontainers

Dev Containers Skill

Expert guidance on creating, configuring, and optimising containerised development environments using the Dev Container Specification. Covers devcontainer.json authoring, Features, Templates, performance, security, multi-container setups, and cloud environments.

Quick Reference Table

Orchestration Protocol

Phase 1 — Classify the Task

Identify which category the user's request falls into:

• Configuration — writing or editing devcontainer.json, Dockerfiles, Compose files
• Tooling — adding Features, authoring custom Features, or using Templates
• Advanced — multi-container, DinD/DooD, Kubernetes, cloud environments
• Optimisation — caching, pre-built images, named volumes, disk I/O
• Security — non-root users, UID mapping, secrets, hardened images
• Troubleshooting — permission errors, slow builds, SSH/GPG credential issues

Phase 2 — Load the Right Resource

Load the resource indicated in the Quick Reference Table. For complex tasks spanning multiple areas (e.g. "set up a secure multi-container environment with fast builds"), load both relevant files.

Phase 3 — Execute

Apply the guidance from the loaded resource. Use concrete examples from the resource files. For configuration tasks, produce a complete, commented devcontainer.json snippet.

Common Task Workflows

Workflow 1: Create a New Dev Container from Scratch

1. Load references/core-concepts.md for the full property reference
2. Choose orchestration method: image (simplest), build.dockerfile, or dockerComposeFile
3. Add features for tools (Node.js, Python, Git, Docker CLI, etc.)
4. Set remoteUser to a non-root user for security
5. Add customizations.vscode.extensions and settings for IDE consistency
6. Add postCreateCommand to install dependencies automatically
7. Add forwardPorts for any app ports

{
  "name": "My Project",
  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
  "features": {
    "ghcr.io/devcontainers/features/node:1": { "version": "20" },
    "ghcr.io/devcontainers/features/git:1": {}
  },
  "customizations": {
    "vscode": {
      "extensions": ["dbaeumer.vscode-eslint", "esbenp.prettier-vscode"],
      "settings": { "editor.formatOnSave": true }
    }
  },
  "postCreateCommand": "npm install",
  "forwardPorts": [3000],
  "remoteUser": "node"
}

Workflow 2: Add a Tool via Features

1. Load references/features-templates.md
2. Browse the official registry or GitHub Container Registry
3. Add the feature with a pinned version to devcontainer.json
4. Use overrideFeatureInstallOrder if ordering matters

Workflow 3: Multi-Container Setup with Docker Compose

1. Load references/advanced-config.md
2. Create docker-compose.yml for services (app, database, cache)
3. Create docker-compose.dev.yml for development overrides (source mounts, debug ports)
4. Set dockerComposeFile to both files in devcontainer.json
5. Set service to the container the IDE should attach to
6. Set shutdownAction: "none" to keep services running when IDE closes

Workflow 4: Speed Up Dev Container Builds

1. Load references/performance-security.md
2. Order Dockerfile instructions from least-changed to most-changed
3. Use RUN --mount=type=cache for package managers
4. Use named volumes for node_modules / heavy dependency directories
5. Pre-build and push image in CI; reference the pre-built image in devcontainer.json

Workflow 5: Troubleshoot a Permission or Credential Issue

1. Load references/troubleshooting.md
2. For UID mismatch: ensure updateRemoteUserUID: true (default on Linux)
3. For SSH: ensure local SSH agent is running; the extension auto-forwards it
4. For Git inside container: use SSH agent forwarding; do not copy private keys

Resource Summaries

Best Practices

• Version-pin everything — pin Features (feature:1) and base images (python:3.12) for reproducibility
• Non-root by default — always set remoteUser to a non-root user; use updateRemoteUserUID: true on Linux
• Automate setup — use postCreateCommand to install dependencies so the environment is immediately usable
• Don't modify production Compose — use a docker-compose.dev.yml override for dev-specific additions
• Pre-build images in CI — reduces startup from minutes to seconds; embed metadata in image labels
• Never bake secrets into images — use SSH agent forwarding, BuildKit secret mounts, or .env files (git-ignored)
• Named volumes for heavy directories — on macOS/Windows, mount node_modules etc. into named volumes for native I/O speed

External References

• Dev Container Specification — official specification and schema
• devcontainer.json reference — full property reference
• Official Features registry — browse available Features
• Official Templates registry — browse available Templates
• VS Code Dev Containers docs — IDE integration guide
• GitHub Codespaces docs — cloud-hosted containers
• DevPod docs — open-source provider-agnostic cloud dev environments
• devcontainers/cli — reference CLI implementation