Devcontainers Best Practices

Devcontainers Best Practices

This skill guides you to the right documentation and references for the Development Container ecosystem. Use it when working with devcontainer.json, selecting Features or Templates, or when the user asks about dev containers, containers.dev, or supporting tools.

Quick start

Minimal devcontainer.json using an image and a Feature: "image": "mcr.microsoft.com/devcontainers/base:ubuntu", "features": { "ghcr.io/devcontainers/features/git:1": {} }. For property details and validation, see [Quick lookup](#quick-lookup) item 1 and [references/schema.md](references/schema.md).

When to use this skill

• Editing or validating devcontainer.json
• Looking up a property (syntax, type, tool support)
• Choosing or referencing a Feature or Template
• Checking which tools support the spec or have tool-specific properties/limitations
• Understanding the spec (lifecycle, merge logic, image metadata)
• Authoring or publishing a Dev Container Feature (see the Authoring section in [references/features.md](references/features.md) and the containers.dev authoring guide)
• Configuring multiple dev containers (multi-project, shared Compose); see [references/tools.md](references/tools.md) and VS Code / multi-container docs

Canonical sources

All content in this skill and its references is traceable to these sources:

• Spec and reference: containers.dev/implementors/spec, containers.dev/implementors/jsonreference
• Schema: containers.dev/implementors/json_schema
• Guides: containers.dev/guides (prebuilds, using Dockerfile/Compose, Feature authoring best practices, GitLab CI)
• Supporting tools: devcontainers.github.io/supporting
• Features: containers.dev/implementors/features, github.com/devcontainers/features
• Templates: containers.dev/implementors/templates, github.com/devcontainers/templates

Reference files

Detailed material is in the references/ directory. Load only what you need.

| Need | File | |------|------| | When to use the full spec, key concepts, merge logic, lifecycle | [references/spec.md](references/spec.md) | | JSON reference vs schema, canonical URLs, how to validate | [references/schema.md](references/schema.md) | | Supporting tools, tool-specific properties, limitations | [references/tools.md](references/tools.md) | | VS Code workflows, requirements, prebuild, ports, extensions, limitations, dotfiles, managing containers | [references/vscode-containers.md](references/vscode-containers.md) | | Tips and tricks (OS, Git, performance, troubleshooting, profile persistence, reporting) | [references/tips-and-tricks.md](references/tips-and-tricks.md) | | Official Features, OCI refs, versioning, options, install order, authoring Features | [references/features.md](references/features.md) | | Official Templates, when to use template vs Feature vs Dockerfile | [references/templates.md](references/templates.md) |

Quick lookup

1. Property or behavior in devcontainer.json

Use the Dev Container metadata reference (or [references/spec.md](references/spec.md)) for property-by-property details. For validation, use the devcontainer.json schema or Dev Container CLI; see [references/schema.md](references/schema.md).

1. Tool support or tool-specific settings

Check devcontainers.github.io/supporting for the list of tools, customizations.* (e.g. customizations.vscode, customizations.codespaces), and limitations. Summary in [references/tools.md](references/tools.md).

1. Advanced scenarios (env vars, mounts, performance, non-root user, remote Docker, multiple containers, Git credentials)

See VS Code Advanced container configuration. Summary and workflow links in [references/vscode-containers.md](references/vscode-containers.md).

1. Multiple dev containers (multi-project, shared Docker Compose)

See [references/tools.md](references/tools.md) “Multiple containers / multi-project” and Chris Ayers – Multiple dev containers.

1. OS-specific or troubleshooting (Git, Docker Desktop, cleanup, logs)

See VS Code Dev Containers Tips and Tricks. Summary in [references/tips-and-tricks.md](references/tips-and-tricks.md).

1. Feature ID, options, or install order

Official Features: containers.dev/features, github.com/devcontainers/features. OCI refs: ghcr.io/devcontainers/features/:. Details in [references/features.md](references/features.md). For authoring Features, see the Authoring section there and containers.dev/guide/feature-authoring-best-practices.

1. Template or "template vs Feature vs Dockerfile"

Official Templates: containers.dev/templates, github.com/devcontainers/templates. When to use which: [references/templates.md](references/templates.md).

1. Spec concepts (lifecycle, merge, image metadata)

Full spec: containers.dev/implementors/spec. Summary: [references/spec.md](references/spec.md).

Best practices (from official docs)

Only apply recommendations that are stated in the spec or official devcontainer documentation; cite the source when relevant.

• Environment variables: Prefer containerEnv over remoteEnv when possible so all processes in the container see the variable and it is not client-specific. Use remoteEnv when the value is not static and you want to avoid rebuilding. (Dev Container metadata reference – containerEnv/remoteEnv.)
• Port forwarding: In most cases use the forwardPorts property rather than appPort; forwarded ports behave like localhost to the application. Use appPort (or Docker Compose ports) when you need published/network-visible ports. (VS Code – Forwarding or publishing a port, Dev Container metadata reference.)
• Pre-build when possible: Pre-building images (e.g. with Dev Container CLI or GitHub Actions) speeds up startup and lets you pin tool versions; image metadata can be inherited so repos need only a minimal devcontainer.json. (VS Code – Pre-building dev container images, containers.dev/guides.)
• Security and trust: Dev container configs and images can run arbitrary commands. Only use configs and images from trusted sources. For sandboxing and security context, see the spec and community articles (e.g. The Red Guild – Where do you run your code with attribution).
• Feature versions: To pin to a specific version, append it to the Feature ID (e.g. from the versions list). The :latest tag is applied implicitly if omitted. (Features – containers.dev.)
• Rebuild after changes: After changing the dev container configuration, rebuild so tools pick up changes (e.g. "Dev Containers: Rebuild Container" or "Codespaces: Rebuild Container" in the command palette, in VS Code or compatible editors such as Cursor). (VS Code Dev Containers extension, GitHub Codespaces.)
• Lifecycle script order: Creation scripts run in this order: onCreateCommand → updateContentCommand → postCreateCommand. If one fails, later scripts are not run. (Dev Container metadata reference – Lifecycle scripts.)

When the spec or official docs do not state a recommendation, do not present it as a best practice; either omit it or phrase it as a suggestion with a clear citation.

Optional / community guidance: Community articles (e.g. Daytona – Ultimate guide to dev containers) suggest practices such as keeping images lightweight, caching dependencies, and using Docker Compose for multi-service setups. Use with attribution and prefer spec/official docs when they conflict.

Summary

• Use this skill when editing devcontainer.json, choosing Features/Templates, authoring Features, or answering questions about dev containers or containers.dev.
• Resolve questions via the canonical URLs above and the reference files under [references/](references/).
• Best practices: cite containers.dev or devcontainers.github.io; only include guidance that appears there. For OS-specific or troubleshooting issues, consult VS Code Dev Containers Tips and Tricks and [references/tips-and-tricks.md](references/tips-and-tricks.md).

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: afonsograca
• Source: afonsograca/devcontainers-best-practices
• License: MIT
• Homepage: https://www.skills.sh/afonsograca/devcontainers-best-practices

Install and usage instructions live in the source repository linked above.