Devcontainer overlays

--devcontainer-overlay layers a second devcontainer.json over the config selected for a workspace:

devsy workspace up <workspace> --devcontainer-overlay ./devcontainer/overlay.json

The overlay is applied during build planning, before substitution and image creation. It supports these fields: image, dockerFile, context, build, dockerComposeFile, service, runServices, initializeCommand, features and overrideFeatureInstallOrder. It does not enable arbitrary config replacement. The primary config stays the effective origin. Paths inside the overlay, including local features, are relative to the file that declares them.

How fields combineCopy Anchor Link

• Same build type. Fields missing from the overlay keep the primary value.
• Different build type (image, Dockerfile or Compose). Fields from the previous type are cleared before the new selector applies. An overlay that selects Compose can replace a primary image config without keeping its image.
• build. args merge by key, with overlay keys winning. target, cacheFrom and options replace the primary values.
• dockerFile and context. The top-level forms are the same as build.dockerfile and build.context. Setting both forms to different paths is an error.
• Compose. dockerComposeFile takes a path or a list, and replaces the primary selection as a whole. service replaces the service. runServices replaces the sidecar list. Relative paths resolve from the declaring file, including files reached through extends. Paths inside the Compose YAML follow Docker Compose's own rules.
• Required selectors. They cannot be null or empty. Devsy reports an error instead of guessing.
• initializeCommand. The overlay's command replaces the primary one. It runs on the host before the build, in the workspace root. A string runs through the shell, an array runs directly, and an object runs its commands in parallel. To disable the primary command, use "", [] or {}. null is an error.
• runServices. Use [] to clear the primary list.
• Features. Precedence is primary config, then overlay, then CLI --features.
• Runtime metadata. The existing overlay behavior still applies. For example, remoteEnv values combine, with the overlay winning on matching keys.

The feature lockfile stays next to the primary config. Structural overlays cannot attach to or replace a containerID config.

Applying changesCopy Anchor Link

A missing or malformed overlay is an error. Devsy reads it before replacing an existing workspace, so a failure leaves the current workspace available. To apply a structural change to an existing workspace, recreate it:

devsy workspace up <workspace> --recreate --devcontainer-overlay ./devcontainer/overlay.json

After a successful creation, workspace cleanup uses the recorded invocation, so you can still delete the workspace if the overlay file is later removed or broken.