devcontainers/spec: Development Containers: Use a container as a full-featured development environment.

Development Containers: Use a container as a full-featured development environment. - devcontainers/spec

Summary

The devcontainers/spec repository defines a specification for development containers, centered on a devcontainer.json metadata file written in JSON-with-Comments (jsonc). It is a specification rather than a runnable tool, and the runtimes that apply it live in sibling projects. Companion repositories provide the reference CLI and CI integrations.

What it is useful for

The specification gives editors, CI systems, and container tooling a shared way to describe what a project needs in order to build and run. A devcontainer.json can declare the container image, lifecycle scripts, ports, and tools required for a codebase, so the same configuration describes both a local coding environment and a CI pipeline. The spec also defines how the same metadata can travel with an image through a devcontainer.metadata image label, rather than living only in the project tree.

It is useful when teams want to standardize onboarding, avoid drift between local and CI environments, and keep toolchain setup out of contributor READMEs. The specification covers both a simplified, single-container option and Docker Compose-based setups, so it fits small scripts as well as multi-service projects.

How engineers can use it

To use the spec, an engineer typically adds a devcontainer.json (or .devcontainer/devcontainer.json) to a repository. The exact properties are defined under the docs/specs folder of this repository, and in-progress additions are tracked in the proposals folder, which is the place to look if a needed option is not yet in the stable spec.

The repository itself does not start containers. Applying a devcontainer.json to launch or build a container is done with the open-source reference CLI in devcontainers/cli, and reusing the same setup in pipelines is handled by devcontainers/ci, which provides a GitHub Action and an Azure DevOps Task. Spec-maintained features and starter templates live in devcontainers/features and devcontainers/templates, which is where engineers look when they want a prebuilt configuration to copy from.

A practical limitation: there is nothing to install from this repository directly, because it contains the specification text under the Creative Commons Attribution 4.0 license, not an implementation. Engineers who want to read the schema, review a proposal, or check how image-label metadata should be structured should start in docs/specs; everything else is a separate project.