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 supports these fields: image, dockerFile, context, build, dockerComposeFile, service, runServices, initializeCommand, features and overrideFeatureInstallOrder. Paths inside the overlay, including local features, are relative to the overlay file.

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. Selector fields such as image, dockerFile and service cannot be null or empty.
• 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. Values such as remoteEnv 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

Devsy reads the overlay before replacing an existing workspace, so a missing or malformed file leaves that workspace running. The exception is stale persisted state from a different workspace, which Devsy removes before reading the overlay. To apply a structural change to an existing workspace, recreate it:

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

You can still delete the workspace if the overlay file is later removed or broken.

Restarting Compose workspacesCopy Anchor Link

Compose workspaces keep the resolved feature and overlay lifecycle metadata in the container. SSH starts the existing container and runs its saved lifecycle hooks without the overlay file. Reconnecting to an already running container does not rerun postStartCommand.

Changing feature IDs, options, or installation order requires workspace up --recreate. SSH does not install features, rebuild images, or replace a stopped container. If the saved Compose files are unavailable, restore them or run workspace up.

If Devsy reports missing or invalid lifecycle metadata, recreate the workspace with the original configuration and overlay. Recreation replaces the container, so back up data stored outside persistent mounts first.