Devcontainers Knowledge Patch

Dev Containers

Use this skill when working with Dev Container configuration, the Dev Container CLI, Feature packages, Feature lockfiles, or Template packages. Read only the reference that matches the task, then verify repository-specific configuration before making changes.

Working method

1. Locate the active devcontainer.json using the discovery rules below.
2. Determine whether the project uses an image, a Dockerfile, or Compose.
3. Separate container-creation settings from remote-process settings.
4. Check the installed CLI version before depending on recently added behavior.
5. Preserve .devcontainer-lock.json unless the task deliberately updates Feature versions or opts out of locking.
6. When authoring a Feature or Template, validate its package layout, identity, option substitution, and dependency behavior as applicable.
7. Keep installers and lifecycle operations safe to repeat.

Reference index

Compatibility and deprecated assumptions

Check these points before relying on familiar but outdated behavior:

• Treat devcontainer.metadata as a JSON array, including when it contains one entry.
• Use the current .devcontainer-lock.json filename. Older material may refer to the undotted devcontainer-lock.json.
• Expect build and up to generate the lockfile by default on CLI 0.87.0 and later.
• Prefer --no-lockfile and --frozen-lockfile. The corresponding --experimental-* flags are deprecated and warn when used.
• Do not script devcontainer stop or devcontainer down; neither command is implemented.
• Do not expect Features supplied with --additional-features to appear in the lockfile on CLI 0.86.1 and later.
• Handle Docker 29 container start events without the fields Docker removed.
• Expect old devcontainers-contrib Feature references to redirect to devcontainers-extra on CLI 0.79.0 and later.
• On Docker Engine 23.0.0 and later, do not assume the CLI must download and inject the dockerfile:1.4 frontend.

CLI quick reference

For restricted and alternate-engine environments:

• CLI 0.74.0 ignores an unusable, non-writable HOME.
• Avoid combining Podman --uidmap or --gidmap with conflicting --userns settings.
• Omit --userns=keep-id when running Podman as root.
• Expect Podman invocations to use label=disable, rather than z, on CLI 0.80.0 and later.
• CLI 0.80.1 supports Debian latest images without adduser and addgroup.
• Failed lifecycle commands expose their output, and an OCI registry 403 triggers reauthentication, on CLI 0.73.0 and later.

Configuration quick reference

Search a workspace in this order:

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

Multiple configurations are valid. Select one explicitly when the tool or workflow supports more than one.

Keep these roles distinct:

On Linux, use updateRemoteUserUID: true with a configured container or remote user when bind-mounted files need matching local UID/GID ownership. An implementation may skip the rewrite when no bind mounts exist or the engine already translates identities.

Lifecycle quick reference

On first creation, apply container-level mounts, environment, and user settings before these ordered stages:

1. onCreateCommand
2. updateContentCommand
3. postCreateCommand

postCreateCommand is backgrounded by default. waitFor controls the blocking stage and defaults to updateContentCommand. On resume, restart containers, perform implementation-specific setup, then also run postStartCommand and postAttachCommand.

A lifecycle property may be an object of uniquely named commands. Run those entries in parallel and require every entry to succeed. For each lifecycle stage, run Feature contributions sequentially in Feature installation order before the user's corresponding command.

Metadata merge quick reference

Merge image metadata snippets in order and apply devcontainer.json last:

• Use any-true semantics for init and privileged.
• Deduplicate and union capabilities, security options, and forwarded ports.
• Collect entrypoints, mounts, and lifecycle commands.
• Resolve conflicting mounts and scalar settings with the last value.
• Merge environment maps with the last value for each variable.
• Replace port attributes as a whole for the affected port.
• Take each maximum in hostRequirements.
• Leave customizations merging to the implementing tool.

Feature authoring quick reference

A Feature directory requires devcontainer-feature.json and an executable install.sh. Match the manifest id to the directory name, keep it lowercase, and supply at least id, version, and name.

Use only string and boolean options. Use proposals for suggestions with free-form input or enum for a strict set. Every option reaches the installer, including defaults for omitted options, through devcontainer-features.env.

Choose dependency declarations by intent:

Do not put options, tags, or digests in installsAfter or overrideFeatureInstallOrder. Treat unresolved or circular hard dependencies, and user ordering that violates dependencies, as errors.

Template authoring quick reference

A Template contains devcontainer-template.json at its root and .devcontainer/devcontainer.json beneath it. Match the manifest id to the Template folder name and keep it unique within the repository or package.

Apply ${templateOption:<optionId>} substitution to every file before copying the Template. Prompt separately for every optionalPaths entry; use an exact relative path for a file and a trailing /* for recursive directory contents. Address a published Template as <oci-registry>/<namespace>/<template>[:<semantic-version>].

Final checks

• Confirm path and user assumptions on the actual container engine and host OS.
• Keep lockfile references lowercase and digest- or checksum-qualified as required by the schema.
• Ensure local Features and differently configured instances remain safe to install more than once.
• Avoid ${devcontainerId} in image-build inputs; use it only for supported per-container runtime resources.
• Preserve an existing Feature's semantic-version sequence when renaming it.
• Consult the detailed reference for any field or behavior before encoding it into reusable automation.