Devcontainers Knowledge Patch

Dev Containers Knowledge Patch

Use this skill when configuring, building, running, or publishing Dev Containers, Features, and Templates. It is especially useful for lifecycle ordering, environment and user selection, metadata merging, lockfiles, dependency ordering, and current CLI behavior.

Reference index

Start with current behavior

Use the current lockfile name and flags

The generated Feature lockfile is .devcontainer-lock.json, beside devcontainer.json. Current build and up commands generate it by default.

devcontainer build --frozen-lockfile
devcontainer up --no-lockfile

Use --frozen-lockfile in reproducible automation: it requires an existing lockfile and rejects changes. Use --no-lockfile only when intentionally opting out. The old --experimental-lockfile and --experimental-frozen-lockfile spellings are deprecated and warn.

Features passed through --additional-features are deliberately excluded from the lockfile. Do not rely on the lockfile to pin those additions.

Do not assume stop or down commands

The CLI does not implement devcontainer stop or devcontainer down. Teardown automation must call the underlying container engine or orchestrator instead.

Parse metadata labels as arrays

devcontainer.metadata is always serialized as a JSON array, including when it contains one entry. Consumers must not special-case a single object.

Keep environment scopes distinct

For image and Dockerfile configurations, containerEnv exists from container creation and is visible to ENTRYPOINT. Compose configurations use the orchestrator's environment settings instead.

remoteEnv affects tool-injected processes after ENTRYPOINT and can change without container recreation. userEnvProbe collects shell-profile values for those processes without forcing every subprocess through that shell.

Configuration quick reference

Discover configurations in the defined order

Within a workspace, check:

1. .devcontainer/devcontainer.json
2. .devcontainer.json
3. .devcontainer/<folder>/devcontainer.json, one subdirectory deep

Multiple valid configurations can coexist, so tools may need to let the user select one.

Separate mount root from working folder

The source stays outside the container and is mounted at /workspace by default. For image and Dockerfile configurations, workspaceMount changes the mount itself. Keep that mount at the repository root in normal use, and use workspaceFolder to select a nested project.

Choose users deliberately

containerUser controls container operations. remoteUser controls lifecycle, editor, and tool processes and defaults to the container user.

On Linux, updateRemoteUserUID: true asks the implementation to align the selected user's UID and GID with the local user before creation. The implementation may skip this when there are no bind mounts or the engine performs identity translation.

{
  "containerUser": "root",
  "remoteUser": "dev",
  "updateRemoteUserUID": true
}

Respect lifecycle readiness

Initial creation applies container mounts, environment, and user settings before onCreateCommand, updateContentCommand, and postCreateCommand, in that order. Remote settings apply only to subsequently launched processes.

postCreateCommand is backgrounded by default. waitFor chooses the readiness barrier and defaults to updateContentCommand. Resume also runs postStartCommand and postAttachCommand after restart and implementation setup.

A lifecycle property can be an object of independently named commands. Its entries run in parallel, and all must succeed:

{
  "postCreateCommand": {
    "dependencies": "npm ci",
    "schema": ["npm", "run", "db:migrate"]
  }
}

Feature authoring quick reference

Meet the package contract

A Feature directory contains devcontainer-feature.json and executable install.sh; other files are packaged beside them. The required manifest fields are id, version, and name. Keep id lowercase and equal to the directory name. The installer runs directly as root during image build.

Feature options are only string or boolean. proposals suggests values but allows other input; enum rejects values outside its list. Defaults are exported even when the user omits an option. Option IDs become uppercase shell variables after non-word characters are replaced and a leading digit/underscore run is collapsed, so tool-version becomes TOOL_VERSION.

Use the intended user variables

Although installation runs as root, use _CONTAINER_USER, _REMOTE_USER, _CONTAINER_USER_HOME, and _REMOTE_USER_HOME to target the development account. Without an explicit remoteUser, the remote values identify the container user.

Model dependencies correctly

Use dependsOn for recursive hard dependencies, including options and version/digest pins. Unresolvable or circular hard dependencies fail creation.

Use installsAfter only as a soft ordering hint for an already queued Feature. Its entries are unversioned IDs and cannot carry options, tags, or digests.

overrideFeatureInstallOrder prioritizes user-requested IDs only after hard and soft dependencies. It cannot violate the dependency graph or include options, tags, or digests.

Make repeated installation safe

The same Feature requested with different options is installed as distinct instances, and local Features are always unique. Make installers and shared-state changes idempotent.

${devcontainerId} is stable per container host across rebuilds and can make entrypoint, mounts, and customizations resources unique. Never use it as an image-build input because it is unavailable while prebuilding an image.

Template authoring quick reference

A Template has devcontainer-template.json at its root and .devcontainer/devcontainer.json beneath it. Its id equals the Template folder name and must be unique in the repository or package.

${templateOption:<optionId>} substitution applies to every file before the Template is copied. Treat substitutions as whole-template text replacement, not as JSON-only interpolation.

List optional files by exact relative path in optionalPaths; use a trailing /* for a directory's recursive contents. Tooling must ask whether to include each listed path before applying the Template.

Published Templates use <oci-registry>/<namespace>/<template>[:<semantic-version>].

Operational checklist

Before creating or rebuilding:

• Resolve the intended configuration when the workspace contains several.
• Keep repository mount placement separate from the nested working directory.
• Verify containerUser, remoteUser, and Linux UID/GID behavior.
• Decide whether automation requires a frozen lockfile.
• Treat metadata labels as arrays.

Before publishing a Feature:

• Validate the package filenames, executable bit, required fields, and ID.
• Test every default and option-derived environment variable.
• Test dependency cycles, ordering, repeated instances, and idempotency.
• Preserve the existing semantic-version line when renaming with legacyIds.

Before publishing a Template:

• Validate the root and .devcontainer layout.
• Exercise default and selected substitutions across every packaged file.
• Confirm every optional path prompt and OCI reference.